Refactor listeners API

nbbrd · Jul 10, 2023 · 9246893 · 9246893
1 parent 420254f
commit 9246893
Show file tree

Hide file tree

Showing 42 changed files with 316 additions and 251 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - ![API] Refactor cache API [#500](https://github.com/nbbrd/sdmx-dl/issues/500)
 - ![API] Refactor network API [#503](https://github.com/nbbrd/sdmx-dl/issues/503)
 - ![API] Remove dialect API [#505](https://github.com/nbbrd/sdmx-dl/issues/505)
+- ![API] Refactor listeners API [#506](https://github.com/nbbrd/sdmx-dl/issues/506)
 - ![SOURCE] Update ECB endpoint [#495](https://github.com/nbbrd/sdmx-dl/issues/495)
 - ![FORMAT] Refactor file format API [#502](https://github.com/nbbrd/sdmx-dl/issues/502)
 - ![PROVIDER] Move curl backend to an external project

diff --git a/sdmx-dl-api/src/main/java/internal/sdmxdl/NoOpCaching.java b/sdmx-dl-api/src/main/java/internal/sdmxdl/NoOpCaching.java
@@ -1,7 +1,9 @@
 package internal.sdmxdl;
 
 import lombok.NonNull;
-import sdmxdl.ext.SdmxSourceConsumer;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import sdmxdl.ErrorListener;
+import sdmxdl.EventListener;
 import sdmxdl.file.FileCache;
 import sdmxdl.file.SdmxFileSource;
 import sdmxdl.file.spi.FileCaching;
@@ -37,12 +39,12 @@ public int getWebCachingRank() {
     }
 
     @Override
-    public @NonNull FileCache getFileCache(@NonNull SdmxFileSource source, @NonNull SdmxSourceConsumer<? super SdmxFileSource, ? super String> listener) {
+    public @NonNull FileCache getFileCache(@NonNull SdmxFileSource ignoreSource, @Nullable EventListener<? super SdmxFileSource> ignoreEvent, @Nullable ErrorListener<? super SdmxFileSource> ignoreError) {
         return FileCache.noOp();
     }
 
     @Override
-    public @NonNull WebCache getWebCache(@NonNull SdmxWebSource source, @NonNull SdmxSourceConsumer<? super SdmxWebSource, ? super String> listener) {
+    public @NonNull WebCache getWebCache(@NonNull SdmxWebSource ignoreSource, @Nullable EventListener<? super SdmxWebSource> ignoreEvent, @Nullable ErrorListener<? super SdmxWebSource> ignoreError) {
         return WebCache.noOp();
     }
 

diff --git a/sdmx-dl-api/src/main/java/sdmxdl/ErrorListener.java b/sdmx-dl-api/src/main/java/sdmxdl/ErrorListener.java
@@ -0,0 +1,16 @@
+package sdmxdl;
+
+import lombok.NonNull;
+
+import java.io.IOException;
+import java.util.function.BiConsumer;
+
+@FunctionalInterface
+public interface ErrorListener<S extends SdmxSource> {
+
+    void accept(@NonNull S source, @NonNull Marker marker, @NonNull CharSequence message, @NonNull IOException error);
+
+    default @NonNull BiConsumer<CharSequence, IOException> asBiConsumer(@NonNull S source, @NonNull Marker marker) {
+        return (message, error) -> accept(source, marker, message, error);
+    }
+}
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/EventListener.java b/sdmx-dl-api/src/main/java/sdmxdl/EventListener.java
@@ -0,0 +1,15 @@
+package sdmxdl;
+
+import lombok.NonNull;
+
+import java.util.function.Consumer;
+
+@FunctionalInterface
+public interface EventListener<S extends SdmxSource> {
+
+    void accept(@NonNull S source, @NonNull Marker marker, @NonNull CharSequence message);
+
+    default @NonNull Consumer<CharSequence> asConsumer(@NonNull S source, @NonNull Marker marker) {
+        return message -> accept(source, marker, message);
+    }
+}
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/Marker.java b/sdmx-dl-api/src/main/java/sdmxdl/Marker.java
@@ -0,0 +1,25 @@
+package sdmxdl;
+
+import lombok.AccessLevel;
+import lombok.NonNull;
+import nbbrd.design.RepresentableAsString;
+import nbbrd.design.StaticFactoryMethod;
+
+@RepresentableAsString
+@lombok.AllArgsConstructor(access = AccessLevel.PRIVATE)
+@lombok.EqualsAndHashCode
+public class Marker implements CharSequence {
+
+    @lombok.experimental.Delegate(types = CharSequence.class)
+    private final @NonNull String value;
+
+    @Override
+    public String toString() {
+        return value;
+    }
+
+    @StaticFactoryMethod
+    public static @NonNull Marker parse(@NonNull CharSequence value) {
+        return new Marker(value.toString());
+    }
+}
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/SdmxManager.java b/sdmx-dl-api/src/main/java/sdmxdl/SdmxManager.java
@@ -19,7 +19,7 @@
 import lombok.NonNull;
 import nbbrd.design.SealedType;
 import nbbrd.design.ThreadSafe;
-import sdmxdl.ext.SdmxSourceConsumer;
+import org.checkerframework.checker.nullness.qual.Nullable;
 import sdmxdl.file.SdmxFileManager;
 import sdmxdl.web.SdmxWebManager;
 
@@ -39,8 +39,7 @@ public abstract class SdmxManager<SOURCE extends SdmxSource> {
 
     public abstract @NonNull LanguagePriorityList getLanguages();
 
-    public abstract @NonNull SdmxSourceConsumer<? super SOURCE, ? super String> getEventListener();
+    public abstract @Nullable EventListener<? super SOURCE> getOnEvent();
 
-    public static final SdmxSourceConsumer<SdmxSource, String> NO_OP_EVENT_LISTENER = (source, t) -> {
-    };
+    public abstract @Nullable ErrorListener<? super SOURCE> getOnError();
 }
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/ext/SdmxSourceBiConsumer.java b/sdmx-dl-api/src/main/java/sdmxdl/ext/SdmxSourceBiConsumer.java
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/ext/SdmxSourceConsumer.java b/sdmx-dl-api/src/main/java/sdmxdl/ext/SdmxSourceConsumer.java
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/file/SdmxFileManager.java b/sdmx-dl-api/src/main/java/sdmxdl/file/SdmxFileManager.java
@@ -21,10 +21,8 @@
 import lombok.AccessLevel;
 import lombok.NonNull;
 import nbbrd.design.StaticFactoryMethod;
-import sdmxdl.Connection;
-import sdmxdl.LanguagePriorityList;
-import sdmxdl.SdmxManager;
-import sdmxdl.ext.SdmxSourceConsumer;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import sdmxdl.*;
 import sdmxdl.file.spi.FileCaching;
 import sdmxdl.file.spi.FileContext;
 import sdmxdl.file.spi.FileReader;
@@ -62,9 +60,9 @@ public class SdmxFileManager extends SdmxManager<SdmxFileSource> {
     @lombok.Builder.Default
     FileCaching caching = FileCaching.noOp();
 
-    @lombok.NonNull
-    @lombok.Builder.Default
-    SdmxSourceConsumer<? super SdmxFileSource, ? super String> eventListener = NO_OP_EVENT_LISTENER;
+    @Nullable EventListener<? super SdmxFileSource> onEvent;
+
+    @Nullable ErrorListener<? super SdmxFileSource> onError;
 
     @lombok.NonNull
     @lombok.Singular
@@ -86,7 +84,8 @@ private FileContext initContext() {
         return FileContext
                 .builder()
                 .languages(languages)
-                .eventListener(eventListener)
+                .onEvent(onEvent)
+                .onError(onError)
                 .caching(caching)
                 .build();
     }

diff --git a/sdmx-dl-api/src/main/java/sdmxdl/file/spi/FileCaching.java b/sdmx-dl-api/src/main/java/sdmxdl/file/spi/FileCaching.java
@@ -7,7 +7,9 @@
 import nbbrd.service.ServiceDefinition;
 import nbbrd.service.ServiceId;
 import nbbrd.service.ServiceSorter;
-import sdmxdl.ext.SdmxSourceConsumer;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import sdmxdl.ErrorListener;
+import sdmxdl.EventListener;
 import sdmxdl.file.FileCache;
 import sdmxdl.file.SdmxFileSource;
 
@@ -26,14 +28,17 @@ public interface FileCaching {
     @ServiceSorter(reverse = true)
     int getFileCachingRank();
 
-    @NonNull FileCache getFileCache(@NonNull SdmxFileSource source, @NonNull SdmxSourceConsumer<? super SdmxFileSource, ? super String> listener);
+    @NonNull FileCache getFileCache(
+            @NonNull SdmxFileSource source,
+            @Nullable EventListener<? super SdmxFileSource> onEvent,
+            @Nullable ErrorListener<? super SdmxFileSource> onError);
 
     @NonNull Collection<String> getFileCachingProperties();
 
-    int UNKNOWN_FILE_CACHING_RANK = -1;
-
     @StaticFactoryMethod
     static @NonNull FileCaching noOp() {
         return NoOpCaching.INSTANCE;
     }
+
+    int UNKNOWN_FILE_CACHING_RANK = -1;
 }
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/file/spi/FileContext.java b/sdmx-dl-api/src/main/java/sdmxdl/file/spi/FileContext.java
@@ -1,9 +1,10 @@
 package sdmxdl.file.spi;
 
 import lombok.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import sdmxdl.ErrorListener;
+import sdmxdl.EventListener;
 import sdmxdl.LanguagePriorityList;
-import sdmxdl.SdmxManager;
-import sdmxdl.ext.SdmxSourceConsumer;
 import sdmxdl.file.FileCache;
 import sdmxdl.file.SdmxFileSource;
 
@@ -19,11 +20,11 @@ public class FileContext {
     @lombok.Builder.Default
     FileCaching caching = FileCaching.noOp();
 
-    @lombok.NonNull
-    @lombok.Builder.Default
-    SdmxSourceConsumer<? super SdmxFileSource, ? super String> eventListener = SdmxManager.NO_OP_EVENT_LISTENER;
+    @Nullable EventListener<? super SdmxFileSource> onEvent;
+
+    @Nullable ErrorListener<? super SdmxFileSource> onError;
 
     public @NonNull FileCache getCache(@NonNull SdmxFileSource source) {
-        return getCaching().getFileCache(source, getEventListener());
+        return getCaching().getFileCache(source, getOnEvent(), getOnError());
     }
 }
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/web/SdmxWebManager.java b/sdmx-dl-api/src/main/java/sdmxdl/web/SdmxWebManager.java
@@ -20,11 +20,9 @@
 import lombok.AccessLevel;
 import lombok.NonNull;
 import nbbrd.design.StaticFactoryMethod;
-import sdmxdl.Connection;
-import sdmxdl.LanguagePriorityList;
-import sdmxdl.SdmxManager;
-import sdmxdl.ext.SdmxSourceConsumer;
-import sdmxdl.web.spi.WebCaching;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import sdmxdl.EventListener;
+import sdmxdl.*;
 import sdmxdl.web.spi.*;
 
 import java.io.IOException;
@@ -45,6 +43,8 @@
 @lombok.EqualsAndHashCode(callSuper = false)
 public class SdmxWebManager extends SdmxManager<SdmxWebSource> {
 
+    public static final Marker WEB_MANAGER_MARKER = Marker.parse("WEB_MANAGER");
+
     @StaticFactoryMethod
     public static @NonNull SdmxWebManager ofServiceLoader() {
         return SdmxWebManager
@@ -82,9 +82,9 @@ public class SdmxWebManager extends SdmxManager<SdmxWebSource> {
     @lombok.Builder.Default
     WebCaching caching = WebCaching.noOp();
 
-    @lombok.NonNull
-    @lombok.Builder.Default
-    SdmxSourceConsumer<? super SdmxWebSource, ? super String> eventListener = NO_OP_EVENT_LISTENER;
+    @Nullable EventListener<? super SdmxWebSource> onEvent;
+
+    @Nullable ErrorListener<? super SdmxWebSource> onError;
 
     @lombok.NonNull
     @lombok.Singular
@@ -146,12 +146,12 @@ public MonitorReport getMonitorReport(@NonNull SdmxWebSource source) throws IOEx
     }
 
     private void checkSourceProperties(SdmxWebSource source, WebDriver driver) {
-        if (eventListener != NO_OP_EVENT_LISTENER) {
+        if (onEvent != null) {
             Collection<String> expected = driver.getSupportedProperties();
             Collection<String> found = source.getProperties().keySet();
             String diff = found.stream().filter(item -> !expected.contains(item)).sorted().collect(Collectors.joining(","));
             if (!diff.isEmpty()) {
-                eventListener.accept(source, "Unexpected properties [" + diff + "]");
+                onEvent.accept(source, WEB_MANAGER_MARKER, "Unexpected properties [" + diff + "]");
             }
         }
     }
@@ -180,7 +180,8 @@ private WebContext initContext() {
                 .caching(caching)
                 .languages(languages)
                 .networking(networking)
-                .eventListener(eventListener)
+                .onEvent(onEvent)
+                .onError(onError)
                 .authenticators(authenticators)
                 .build();
     }

diff --git a/sdmx-dl-api/src/main/java/sdmxdl/web/spi/WebCaching.java b/sdmx-dl-api/src/main/java/sdmxdl/web/spi/WebCaching.java
@@ -7,7 +7,9 @@
 import nbbrd.service.ServiceDefinition;
 import nbbrd.service.ServiceId;
 import nbbrd.service.ServiceSorter;
-import sdmxdl.ext.SdmxSourceConsumer;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import sdmxdl.ErrorListener;
+import sdmxdl.EventListener;
 import sdmxdl.web.SdmxWebSource;
 import sdmxdl.web.WebCache;
 
@@ -26,14 +28,17 @@ public interface WebCaching {
     @ServiceSorter(reverse = true)
     int getWebCachingRank();
 
-    @NonNull WebCache getWebCache(@NonNull SdmxWebSource source, @NonNull SdmxSourceConsumer<? super SdmxWebSource, ? super String> listener);
+    @NonNull WebCache getWebCache(
+            @NonNull SdmxWebSource source,
+            @Nullable EventListener<? super SdmxWebSource> onEvent,
+            @Nullable ErrorListener<? super SdmxWebSource> onError);
 
     @NonNull Collection<String> getWebCachingProperties();
 
-    int UNKNOWN_WEB_CACHING_RANK = -1;
-
     @StaticFactoryMethod
     static @NonNull WebCaching noOp() {
         return NoOpCaching.INSTANCE;
     }
+
+    int UNKNOWN_WEB_CACHING_RANK = -1;
 }
diff --git a/sdmx-dl-api/src/main/java/sdmxdl/web/spi/WebContext.java b/sdmx-dl-api/src/main/java/sdmxdl/web/spi/WebContext.java
@@ -17,12 +17,13 @@
 package sdmxdl.web.spi;
 
 import lombok.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import sdmxdl.ErrorListener;
+import sdmxdl.EventListener;
 import sdmxdl.LanguagePriorityList;
-import sdmxdl.SdmxManager;
-import sdmxdl.web.WebCache;
-import sdmxdl.ext.SdmxSourceConsumer;
 import sdmxdl.web.Network;
 import sdmxdl.web.SdmxWebSource;
+import sdmxdl.web.WebCache;
 
 import java.util.List;
 
@@ -41,9 +42,9 @@ public class WebContext {
     @lombok.Builder.Default
     WebCaching caching = WebCaching.noOp();
 
-    @lombok.NonNull
-    @lombok.Builder.Default
-    SdmxSourceConsumer<? super SdmxWebSource, ? super String> eventListener = SdmxManager.NO_OP_EVENT_LISTENER;
+    @Nullable EventListener<? super SdmxWebSource> onEvent;
+
+    @Nullable ErrorListener<? super SdmxWebSource> onError;
 
     @lombok.NonNull
     @lombok.Singular
@@ -54,7 +55,7 @@ public class WebContext {
     Networking networking = Networking.getDefault();
 
     public @NonNull WebCache getCache(@NonNull SdmxWebSource source) {
-        return getCaching().getWebCache(source, getEventListener());
+        return getCaching().getWebCache(source, getOnEvent(), getOnError());
     }
 
     public @NonNull Network getNetwork(@NonNull SdmxWebSource source) {

diff --git a/sdmx-dl-api/src/main/java/sdmxdl/web/spi/WebMonitoring.java b/sdmx-dl-api/src/main/java/sdmxdl/web/spi/WebMonitoring.java
@@ -5,6 +5,7 @@
 import nbbrd.service.Quantifier;
 import nbbrd.service.ServiceDefinition;
 import nbbrd.service.ServiceId;
+import sdmxdl.Marker;
 import sdmxdl.web.MonitorReport;
 import sdmxdl.web.SdmxWebSource;
 
@@ -28,4 +29,6 @@ MonitorReport getReport(
             @NonNull SdmxWebSource source,
             @NonNull WebContext context
     ) throws IOException, IllegalArgumentException;
+
+    Marker WEB_MONITORING_MARKER = Marker.parse("WEB_MONITORING");
 }