rename OnMatchEventHandler to MatchHandler, so it align with NativeMatchHandler

Author: luka-leko

README.md

@@ -70,7 +70,7 @@ The scratch space, and by extension the scanner object, are modified during the
 A scanner's scan() method requires two arguments. 
    1. First, an object holding the payload for what you want to scan over. 
 The wrapper supports Strings, byte arrays, ByteBuffers (both on-heap and direct), and MemorySegments (both heap and native).
-   2. Second, an [OnMatchEventHandler](src/main/java/com/dynatrace/vectorscan4j/OnMatchEventHandler.java), which is a user-provided callback that gets executed on every match. 
+   2. Second, a [MatchHandler](src/main/java/com/dynatrace/vectorscan4j/MatchHandler.java), which is a user-provided callback that gets executed on every match. 
 Through that callback, the user can pass arbitrary logic to be executed on every match.  
 
 ## Code example
@@ -92,7 +92,7 @@ we want to count how often each pattern exists inside the input:
 
         try (Database database = new Database(exprs, ExecutionMode.BLOCK);
              BlockScanner scanner = new BlockScanner(database)) {
-             OnMatchEventHandler countMatches = (id, from, to, flags) -> {
+             MatchHandler countMatches = (id, from, to, flags) -> {
                 countsById[id]++;
                 return true;
             }; 
@@ -110,7 +110,7 @@ The list of Expression objects specify the set of patterns we want to match. Eve
 starting from 0, in the order in which they are added to the List. A Database object gets instantiated by passing it 
 the list of expressions, and specifying an execution mode. A Scanner object then references the Database 
 (BlockScanner objects for Databases with Block execution mode, and StreamScanner objects for Databases with Stream execution mode)
-For the scan method, you pass it an input, and an OnMatchEventHandler, which is a functional interface that will get executed on every match. It receives 4 arguments:
+For the scan method, you pass it an input, and a MatchHandler, which is a functional interface that will get executed on every match. It receives 4 arguments:
 
 1. The id of the expression that matched.
 2. The byte position of where the match started. Note that by default, vectorscan does not keep track of this value, unless the pattern flag SOM_LEFTMOST is enabled.
@@ -119,7 +119,7 @@ For the scan method, you pass it an input, and an OnMatchEventHandler, which is
 The return value of the callback specifies whether you want the scanning to continue.
 Returning true will continue the scan, while returning false will stop the scanning early.
 
-In this example, the provided OnMatchEventHandler increments the value inside an integer array, and then lets the scan continue.  
+In this example, the provided MatchHandler increments the value inside an integer array, and then lets the scan continue.  
 
 ### Database Serialization/Deserialization
 
@@ -185,7 +185,7 @@ passing it a MemorySegment that points to a non-allocated region of memory might
     try (Database db = new Database(List.of(new Expression("p1")), BLOCK_MODE);
          BlockScanner scanner = new BlockScanner(db);
          Arena arena = Arena.ofConfined()) {
-        OnMatchEventHandler doNothing = (_, _, _, _) -> true;
+        MatchHandler doNothing = (_, _, _, _) -> true;
 
         MemorySegment tiny = arena.allocate(10);
         MemorySegment larger = tiny.reinterpret(200000L);
@@ -197,15 +197,15 @@ passing it a MemorySegment that points to a non-allocated region of memory might
     }
 ```
 
-### 3. Throwing exceptions inside the OnMatchEventHandler upcall
+### 3. Throwing exceptions inside the MatchHandler upcall
 
-Throwing exceptions inside the OnMatchEventHandler will always break the JVM, i.e. you can not catch
+Throwing exceptions inside the MatchHandler will always break the JVM, i.e. you can not catch
 that exception outside the scan call:
 
 ``` java
 try (try (Database db = new Database(List.of(new Expression("p1")), BLOCK_MODE);
      BlockScanner scanner = new BlockScanner(db)) {
-    OnMatchEventHandler throwException = (_, _, _, _) -> {
+    MatchHandler throwException = (_, _, _, _) -> {
         throw new RuntimeException("Hi, try and catch me!");
     };
     try {
@@ -263,4 +263,3 @@ The corresponding third-party notice and license reproduction is provided in:
 
 This wrapper currently supports a core subset of vectorscan's features, but not everything. 
 If additional features are required, do not hesitate to raise issues or submit pull requests directly.
-

src/main/java/com/dynatrace/vectorscan4j/BlockScanner.java

@@ -25,7 +25,7 @@
 /**
  * A {@link Scanner} that operates in block mode: each call to {@code scan(...)} processes a single,
  * self-contained input buffer in isolation. Each scan starts from the initial DFA/NFA state and ends when the entire input
- *  * has been consumed (or the {@link OnMatchEventHandler} requests early termination by returning
+ *  * has been consumed (or the {@link MatchHandler} requests early termination by returning
  *  * {@code false}).
  *
  * <p>Each scanner owns its own native scratch space and is therefore <strong>not</strong> safe to
@@ -69,7 +69,7 @@ public BlockScanner(Database db) {
      * @throws VectorscanException if the native scan call returns an error other than {@link
      *     com.dynatrace.vectorscan4j.constants.ErrorCode#HS_SCAN_TERMINATED HS_SCAN_TERMINATED}
      */
-    public void scan(MemorySegment data, OnMatchEventHandler handler) {
+    public void scan(MemorySegment data, MatchHandler handler) {
         if (data.byteSize() > Integer.MAX_VALUE) {
             throw new IllegalArgumentException("Input MemorySegment is too big.");
         }
@@ -87,7 +87,7 @@ public void scan(MemorySegment data, OnMatchEventHandler handler) {
     /**
      * Scans {@code data} using a <em>native</em> match-event callback supplied by the caller.
      *
-     * <p>Unlike {@link #scan(MemorySegment, OnMatchEventHandler)}, this method passes the
+     * <p>Unlike {@link #scan(MemorySegment, MatchHandler)}, this method passes the
      * caller-provided native function pointer directly to vectorscan, so matches do
      * <strong>not</strong> incur an upcall back into Java. This is intended for hot paths
      * where the per-match Java callback dominates cost.

…ce/vectorscan4j/OnMatchEventHandler.java …dynatrace/vectorscan4j/MatchHandler.javasrc/main/java/com/dynatrace/vectorscan4j/OnMatchEventHandler.java renamed to src/main/java/com/dynatrace/vectorscan4j/MatchHandler.java src/main/java/com/dynatrace/vectorscan4j/OnMatchEventHandler.java renamed to src/main/java/com/dynatrace/vectorscan4j/MatchHandler.java

@@ -24,7 +24,7 @@
  * should continue.
  */
 @FunctionalInterface
-public interface OnMatchEventHandler {
+public interface MatchHandler {
 
     /**
      * Called for every match found during a scan.

src/main/java/com/dynatrace/vectorscan4j/Scanner.java

@@ -44,7 +44,7 @@ abstract class Scanner implements AutoCloseable {
     private final Cleaner.Cleanable cleanable;
 
     static class CallHandlerOnMatch implements VectorscanMatchEventHandler.Function {
-        OnMatchEventHandler handler;
+        MatchHandler handler;
 
         @Override
         public int apply(int id, long from, long to, int flags, MemorySegment context) {
@@ -84,7 +84,7 @@ public void run() {
         }
     }
 
-    protected void setHandler(OnMatchEventHandler handler) {
+    protected void setHandler(MatchHandler handler) {
         this.callHandler.handler = handler;
     }
 
@@ -128,14 +128,14 @@ private void resizeBuffer(long newSize) {
      * Scans the given input string for the patterns that were compiled in the database, emitting a
      * callback for each match.
      *
-     * <p>This is a convenience overload that delegates to {@link #scan(byte[], OnMatchEventHandler)}
+     * <p>This is a convenience overload that delegates to {@link #scan(byte[], MatchHandler)}
      * using {@link StandardCharsets#UTF_8}.
      *
      * @param input   text to scan
      * @param handler callback invoked for each match; return {@code true} to continue scanning,
      *                {@code false} to stop early
      */
-    public void scan(String input, OnMatchEventHandler handler) {
+    public void scan(String input, MatchHandler handler) {
         scan(input.getBytes(StandardCharsets.UTF_8), handler);
     }
 
@@ -152,7 +152,7 @@ public void scan(String input, OnMatchEventHandler handler) {
      * @throws IndexOutOfBoundsException if {@code offset} or {@code length} are invalid for {@code
      *                                   data}
      */
-    public void scan(byte[] data, int offset, int length, OnMatchEventHandler handler) {
+    public void scan(byte[] data, int offset, int length, MatchHandler handler) {
         scan(ByteBuffer.wrap(data, offset, length), handler);
     }
 
@@ -163,7 +163,7 @@ public void scan(byte[] data, int offset, int length, OnMatchEventHandler handle
      * @param handler callback invoked for each match; return {@code true} to continue scanning,
      *                {@code false} to stop early
      */
-    public void scan(byte[] data, OnMatchEventHandler handler) {
+    public void scan(byte[] data, MatchHandler handler) {
         scan(ByteBuffer.wrap(data), handler);
     }
 
@@ -179,7 +179,7 @@ public void scan(byte[] data, OnMatchEventHandler handler) {
      * @param handler callback invoked for each match; return {@code true} to continue scanning,
      *                {@code false} to stop early
      */
-    public void scan(ByteBuffer buf, OnMatchEventHandler handler) {
+    public void scan(ByteBuffer buf, MatchHandler handler) {
         if (buf.isDirect()) {
             MemorySegment data = MemorySegment.ofBuffer(buf);
             scan(data, handler);
@@ -268,7 +268,7 @@ public void scan(ByteBuffer buf, NativeMatchHandler handler) {
      * @param handler callback invoked for each match; return {@code true} to continue scanning,
      *                {@code false} to stop early
      */
-    protected abstract void scan(MemorySegment data, OnMatchEventHandler handler);
+    protected abstract void scan(MemorySegment data, MatchHandler handler);
 
     /**
      * Implementation hook for the no-upcall native-callback path used by concrete scanner types

src/main/java/com/dynatrace/vectorscan4j/StreamScanner.java

@@ -29,7 +29,7 @@
  *
  * <p>Stream scanning preserves matcher state across successive {@code
  * scan(...)} calls, which allows matches to span chunk boundaries. The stream state can be reset
- * with {@link #resetStream(OnMatchEventHandler handler)} or terminated with {@link #closeStream(OnMatchEventHandler)}. After
+ * with {@link #resetStream(MatchHandler handler)} or terminated with {@link #closeStream(MatchHandler)}. After
  * closing, a new state can be created via {@link #openStream()}.
  *
  * <p>Always close this scanner to release native resources deterministically. Prefer
@@ -76,7 +76,7 @@ public StreamScanner(Database db) {
      *     {@code false} to stop early
      * @throws VectorscanException if vectorscan reports an error other than early termination
      */
-    public void scan(MemorySegment data, OnMatchEventHandler handler) {
+    public void scan(MemorySegment data, MatchHandler handler) {
         if (database.isClosed()) {
             throw new IllegalStateException("Database was already closed.");
         }
@@ -96,7 +96,7 @@ public void scan(MemorySegment data, OnMatchEventHandler handler) {
     /**
      * Opens a new native stream state for this scanner.
      *
-     * <p>Use this after {@link #closeStream(OnMatchEventHandler)} when starting a fresh stream.
+     * <p>Use this after {@link #closeStream(MatchHandler)} when starting a fresh stream.
      *
      * @throws VectorscanException if vectorscan cannot open the stream
      */
@@ -120,7 +120,7 @@ public void openStream() {
      * @param handler callback used for any matches emitted during the reset
      * @throws VectorscanException if vectorscan reports an error during reset
      */
-    public void resetStream(OnMatchEventHandler handler) {
+    public void resetStream(MatchHandler handler) {
         setHandler(handler);
         int ans = hs_reset_stream(stream, 0, scratch, funcPtr, MemorySegment.NULL);
         if (ans != HS_SUCCESS.getCode()) {
@@ -138,7 +138,7 @@ public void resetStream(OnMatchEventHandler handler) {
      * @param handler callback used for any close-time matches
      * @throws VectorscanException if vectorscan reports an error while closing the stream
      */
-    public void closeStream(OnMatchEventHandler handler) {
+    public void closeStream(MatchHandler handler) {
         if (!streamOpen) return;
         setHandler(handler);
         int ans = hs_close_stream(stream, scratch, funcPtr, MemorySegment.NULL);

src/main/java/com/dynatrace/vectorscan4j/constants/Flags.java

@@ -16,7 +16,7 @@
 package com.dynatrace.vectorscan4j.constants;
 
 import com.dynatrace.vectorscan4j.BlockScanner;
-import com.dynatrace.vectorscan4j.OnMatchEventHandler;
+import com.dynatrace.vectorscan4j.MatchHandler;
 import java.lang.foreign.MemorySegment;
 
 /** Pattern compilation flags for expressions. */
@@ -55,7 +55,7 @@ public enum Flags {
      * <p>This flag sets the expression's match ID to match at most once. In streaming mode, this
      * means that the expression will return only a single match over the lifetime of the stream,
      * rather than reporting every match as per standard Vectorscan semantics. In block mode, only the
-     * first match for each invocation of {@link BlockScanner#scan(MemorySegment, OnMatchEventHandler)
+     * first match for each invocation of {@link BlockScanner#scan(MemorySegment, MatchHandler)
      * BlockScanner.scan(...)} will be returned.
      *
      * <p>Note: The use of this flag in combination with {@link #SOM_LEFTMOST} is not currently

src/main/java/com/dynatrace/vectorscan4j/internal/NativeLoader.java

@@ -66,7 +66,7 @@ static String normalizeOs(String osName) {
         if (os.contains("mac") || os.contains("darwin")) {
             return "macos";
         }
-        if (os.contains("nux") || os.contains("nix") || os.contains("linux")) {
+        if (os.contains("nux") || os.contains("nix")) {
             return "linux";
         }
         return os.replace(' ', '_');

src/test/java/com/dynatrace/vectorscan4j/BlockScannerTests.java

@@ -40,7 +40,7 @@ public class BlockScannerTests {
             new Expression("pattern3", EnumSet.of(SOM_LEFTMOST, CASELESS)));
     static int nMatches = 0;
 
-    final OnMatchEventHandler doNothing = (_, _, _, _) -> true;
+    final MatchHandler doNothing = (_, _, _, _) -> true;
 
     @Test
     void databaseWrongMode() {
@@ -68,8 +68,8 @@ void defaultScan() {
 
     @Test
     void earlyStopScan() {
-        // if an OnMatchEventHandler returns false, the execution of the engine stops early.
-        OnMatchEventHandler incrementAndStop = (_, _, _, _) -> {
+        // if a MatchHandler returns false, the execution of the engine stops early.
+        MatchHandler incrementAndStop = (_, _, _, _) -> {
             nMatches += 1;
             return false;
         };
@@ -118,7 +118,7 @@ void emptyInput() {
         try (Database db = new Database(expressions, BLOCK_MODE);
                 BlockScanner scanner = new BlockScanner(db)) {
             List<Integer> matchedIds = new ArrayList<>();
-            OnMatchEventHandler collect = (id, _, _, _) -> {
+            MatchHandler collect = (id, _, _, _) -> {
                 matchedIds.add(id);
                 return true;
             };
@@ -170,7 +170,7 @@ void byteBufferRangeRespected() {
                 BlockScanner scanner = new BlockScanner(db)) {
             ByteBuffer buf = ByteBuffer.wrap("pattern1__pattern1__pattern1".getBytes(StandardCharsets.UTF_8));
             List<Integer> matchedIds = new ArrayList<>();
-            OnMatchEventHandler collect = (id, _, _, _) -> {
+            MatchHandler collect = (id, _, _, _) -> {
                 matchedIds.add(id);
                 return true;
             };
@@ -446,7 +446,7 @@ void usingScannerFromMultipleThreadsThrowsVectorscanException() throws Exception
         try {
             CountDownLatch stop = new CountDownLatch(1);
             CountDownLatch scannerInUse = new CountDownLatch(1);
-            OnMatchEventHandler handler = (_, _, _, _) -> {
+            MatchHandler handler = (_, _, _, _) -> {
                 try {
                     scannerInUse.countDown();
                     stop.await();
@@ -477,7 +477,7 @@ void twoScannersWithSameDatabaseCanScanConcurrently() throws Exception {
                 List<Integer> scanner1Matches = Collections.synchronizedList(new ArrayList<>());
                 List<Integer> scanner2Matches = Collections.synchronizedList(new ArrayList<>());
 
-                OnMatchEventHandler handler1 = (id, _, _, _) -> {
+                MatchHandler handler1 = (id, _, _, _) -> {
                     scanner1Matches.add(id);
                     handlersEntered.countDown();
                     try {
@@ -488,7 +488,7 @@ void twoScannersWithSameDatabaseCanScanConcurrently() throws Exception {
                     }
                     return true;
                 };
-                OnMatchEventHandler handler2 = (id, _, _, _) -> {
+                MatchHandler handler2 = (id, _, _, _) -> {
                     scanner2Matches.add(id);
                     handlersEntered.countDown();
                     try {

src/test/java/com/dynatrace/vectorscan4j/DatabaseTests.java

@@ -41,7 +41,7 @@ public class DatabaseTests {
             new Expression("pattern3", EnumSet.of(SOM_LEFTMOST, CASELESS)));
     static int nMatches = 0;
 
-    private final OnMatchEventHandler countMatch = (_, _, _, _) -> {
+    private final MatchHandler countMatch = (_, _, _, _) -> {
         nMatches += 1;
         return true;
     };

src/test/java/com/dynatrace/vectorscan4j/RegexFeaturesTests.java

@@ -25,7 +25,7 @@
 
 public class RegexFeaturesTests {
     static int nMatches = 0;
-    static final OnMatchEventHandler countMatch = (_, _, _, _) -> {
+    static final MatchHandler countMatch = (_, _, _, _) -> {
         nMatches += 1;
         return true;
     };