refactor: construct selectors using builder pattern (#10)

Co-authored-by: Florent Biville <445792+fbiville@users.noreply.github.com>

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: maven
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 10
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: weekly

pom.xml

@@ -398,6 +398,7 @@
                 <configuration>
                     <source>${java.version}</source>
                     <target>${java.version}</target>
+                    <compilerArgument>-Werror</compilerArgument>
                 </configuration>
             </plugin>
         </plugins>
@@ -413,6 +414,9 @@
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-javadoc-plugin</artifactId>
+                        <configuration>
+                            <excludePackageNames>org.neo4j.cdc.client.pattern</excludePackageNames>
+                        </configuration>
                         <executions>
                             <execution>
                                 <id>attach-javadocs</id>

src/main/java/org/neo4j/cdc/client/CDCClient.java

@@ -37,7 +37,7 @@
 import reactor.core.publisher.Mono;
 
 /**
- * @author Gerrit Meier
+ * Default {@link CDCService} implementation.
  */
 public class CDCClient implements CDCService {
     private final Logger log = LoggerFactory.getLogger(CDCClient.class);
@@ -50,21 +50,57 @@ public class CDCClient implements CDCService {
     private final SessionConfigSupplier sessionConfigSupplier;
     private final Duration streamingPollInterval;
 
+    /**
+     * Construct an instance from a driver and an optional list of selectors.
+     *
+     * @param driver Driver instance to use
+     * @param selectors List of selectors to query changes for
+     *
+     * @see Selector
+     */
     public CDCClient(Driver driver, Selector... selectors) {
         this(driver, Duration.ofSeconds(1), selectors);
     }
 
+    /**
+     * Construct an instance from a driver, a poll interval and an optional list of selectors.
+     *
+     * @param driver Driver instance to use
+     * @param streamingPollInterval Polling interval to mimic streaming when using @link{stream} method
+     * @param selectors List of selectors to query changes for
+     *
+     * @see Selector
+     */
     public CDCClient(Driver driver, Duration streamingPollInterval, Selector... selectors) {
         this.driver = Objects.requireNonNull(driver);
         this.sessionConfigSupplier = () -> SessionConfig.builder().build();
         this.streamingPollInterval = Objects.requireNonNull(streamingPollInterval);
         this.selectors = selectors == null ? List.of() : Arrays.asList(selectors);
     }
 
+    /**
+     * Construct an instance from a driver, a session config supplier and an optional list of selectors.
+     *
+     * @param driver Driver instance to use
+     * @param sessionConfigSupplier a supplier to customise session configuration
+     * @param selectors List of selectors to query changes for
+     *
+     * @see Selector
+     */
     public CDCClient(Driver driver, SessionConfigSupplier sessionConfigSupplier, Selector... selectors) {
         this(driver, sessionConfigSupplier, Duration.ofSeconds(1), selectors);
     }
 
+    /**
+     * Construct an instance from a driver, a session config supplier, a poll interval and an optional list of selectors.
+     *
+     * @param driver Driver instance to use
+     * @param sessionConfigSupplier a supplier to customise session configuration
+     * @param streamingPollInterval Polling interval to mimic streaming when using @link{stream} method
+     * @param selectors List of selectors to query changes for
+     *
+     * @see Selector
+     */
     public CDCClient(
             Driver driver,
             SessionConfigSupplier sessionConfigSupplier,

src/main/java/org/neo4j/cdc/client/CDCService.java

@@ -22,15 +22,43 @@
 import reactor.core.publisher.Mono;
 
 /**
- * @author Gerrit Meier
+ * <code>CDCService</code> enables callers to track changes happening in a Neo4j database.
  */
 public interface CDCService {
 
+    /**
+     * Returns the change identifier for the earliest available change.
+     *
+     * @return change identifier
+     */
     Mono<ChangeIdentifier> earliest();
 
+    /**
+     * Returns the change identifier for the last committed transaction.
+     *
+     * @return change identifier
+     */
     Mono<ChangeIdentifier> current();
 
+    /**
+     * Returns the changes that happened to the database after the given change identifier.
+     * The returned Flux completes when we reach the end of change stream.
+     *
+     * @param from change identifier to query changes from.
+     * @return change events
+     */
     Flux<ChangeEvent> query(ChangeIdentifier from);
 
+    /**
+     * Returns the changes that happened to the database after the given change identifier.
+     * The returned Flux does not complete, and continues querying for new changes until the
+     * Flux subscription is closed.
+     * <p>
+     * <i>Change Data Capture feature currently does not support streaming, and this method
+     * mimics streaming through polling.</i>
+     *
+     * @param from change identifier to query changes from.
+     * @return change events
+     */
     Flux<ChangeEvent> stream(ChangeIdentifier from);
 }

src/main/java/org/neo4j/cdc/client/model/CaptureMode.java

@@ -16,8 +16,22 @@
  */
 package org.neo4j.cdc.client.model;
 
+/**
+ * Capture Mode
+ */
 public enum CaptureMode {
+    /**
+     * CDC is disabled.
+     */
     OFF,
+    /**
+     * Changes are captured as the difference between before and after states of each changed entity
+     * (i.e. they only contain removals, updates and additions).
+     */
     DIFF,
+    /**
+     * Changes are recorded as a complete copy of the before and after states of each changed entity
+     * (i.e. they contain the full node/relationship, regardless of the extent to which they were altered).
+     */
     FULL
 }

src/main/java/org/neo4j/cdc/client/model/ChangeEvent.java

@@ -18,6 +18,9 @@
 
 import java.util.Objects;
 
+/**
+ * Change event.
+ */
 public class ChangeEvent {
 
     private final ChangeIdentifier id;
@@ -34,22 +37,52 @@ public ChangeEvent(ChangeIdentifier id, Long txId, Integer seq, Metadata metadat
         this.event = Objects.requireNonNull(event);
     }
 
+    /**
+     * A unique change identifier that identifies this change record.
+     * It can be used to query changes from this change onward.
+     *
+     * @return change identifier
+     */
     public ChangeIdentifier getId() {
         return this.id;
     }
 
+    /**
+     * A number identifying which transaction the change happened in, unique in combination with seq.
+     * Transaction identifiers are not continuous (some transactions, such as system and schema commands,
+     * are not recorded in change data capture and cause gaps in the transaction identifiers).
+     *
+     * @return transaction id
+     */
     public Long getTxId() {
         return this.txId;
     }
 
+    /**
+     * A number used for ordering changes that happened in the same transaction.
+     * The order of changes observed in the output does not necessarily correspond to the order in which
+     * changes were applied during the transaction.
+     *
+     * @return sequence
+     */
     public Integer getSeq() {
         return this.seq;
     }
 
+    /**
+     * Other useful information about the transaction.
+     *
+     * @return metadata
+     */
     public Metadata getMetadata() {
         return this.metadata;
     }
 
+    /**
+     * Details about the actual data change.
+     *
+     * @return event
+     */
     public Event getEvent() {
         return this.event;
     }

src/main/java/org/neo4j/cdc/client/model/ChangeIdentifier.java

@@ -19,13 +19,21 @@
 import java.util.Objects;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Change identifier that identifies a change record.
+ */
 public class ChangeIdentifier {
     private final String id;
 
     public ChangeIdentifier(@NotNull String id) {
         this.id = Objects.requireNonNull(id);
     }
 
+    /**
+     * Identifier as a string value.
+     *
+     * @return identifier
+     */
     public String getId() {
         return this.id;
     }