documented the public APIs for main functions

Author: danrusei

README.md

@@ -45,7 +45,7 @@ The Java client library for interacting with Danube Messaging Broker platform.
 
 ```xml
 <dependency>
-    <groupId>com.danubemessaging</groupId>
+    <groupId>com.danube-messaging</groupId>
     <artifactId>danube-client</artifactId>
     <version>0.2.0</version>
 </dependency>
@@ -54,7 +54,7 @@ The Java client library for interacting with Danube Messaging Broker platform.
 ### Gradle
 
 ```groovy
-implementation 'com.danubemessaging:danube-client:0.2.0'
+implementation 'com.danube-messaging:danube-client:0.2.0'
 ```
 
 **Requirements:** Java 21 or later.
@@ -225,7 +225,7 @@ docker compose ps
 
 # 3. Run the integration tests from the repository root
 cd ..
-mvn -pl danube-client -Pfailsafe verify
+mvn -pl danube-client -Pintegration-tests verify
 
 # 4. Stop the cluster when done
 cd docker/

RELEASE.md

@@ -1,70 +1,155 @@
 # Release guide (Maven Central)
 
-This project is configured for Sonatype OSSRH publishing under the `release` Maven profile.
+This project publishes to Maven Central via the **Sonatype Central Portal** (`central.sonatype.com`).
+The `release` Maven profile handles sources jar, javadoc jar, GPG signing, and upload automatically.
 
-## 1) Prerequisites
+---
 
-1. Sonatype OSSRH account with publish access for `com.danubemessaging`.
-2. GPG key pair available locally.
-3. `~/.m2/settings.xml` configured with server credentials:
+## 1) One-time setup: Central Portal account
+
+> Skip this section if the account already exists.
+
+1. Go to **https://central.sonatype.com** and sign up (GitHub SSO works).
+2. Click **Namespaces** → **Add Namespace**.
+3. Enter `com.danube-messaging`.
+4. Sonatype will show a **DNS TXT verification token**. Add it to the `danube-messaging.com` DNS:
+   ```
+   TXT  @  sonatype-central-verification=<token>
+   ```
+5. Click **Verify Namespace**. Once verified the namespace is permanently linked to your account.
+
+---
+
+## 2) One-time setup: Portal user token (credentials)
+
+1. In the Central Portal: **Account** → **Generate User Token**.
+2. Copy the `username` and `password` values shown.
+3. Add them to `~/.m2/settings.xml`:
 
 ```xml
 <settings>
   <servers>
     <server>
-      <id>ossrh</id>
-      <username>${env.OSSRH_USERNAME}</username>
-      <password>${env.OSSRH_PASSWORD}</password>
+      <id>central</id>
+      <username>YOUR_TOKEN_USERNAME</username>
+      <password>YOUR_TOKEN_PASSWORD</password>
     </server>
   </servers>
 </settings>
 ```
 
-4. Environment variables set for CI/local release:
+> **Never** commit these credentials. Use environment variable substitution if needed:
+> ```xml
+> <username>${env.CENTRAL_TOKEN_USERNAME}</username>
+> <password>${env.CENTRAL_TOKEN_PASSWORD}</password>
+> ```
+
+---
+
+## 3) One-time setup: GPG signing key
 
 ```bash
-export OSSRH_USERNAME=...
-export OSSRH_PASSWORD=...
-export GPG_TTY=$(tty)
+# Generate a key (if you don't have one)
+gpg --gen-key
+
+# List keys and note the key ID
+gpg --list-secret-keys --keyid-format=long
+
+# Publish the public key to a keyserver
+gpg --keyserver keyserver.ubuntu.com --send-keys <KEY_ID>
 ```
 
-If using passphrase-based signing in CI, also pass:
+Set the passphrase in your environment for headless signing:
 
 ```bash
--Dgpg.passphrase=...
+export GPG_TTY=$(tty)
 ```
 
-## 2) Local verification (no deploy)
+---
+
+## 4) Local verification (no deploy)
+
+Before publishing, verify that all artifacts build and sign correctly:
 
 ```bash
 mvn -Prelease -DskipTests verify
 ```
 
-This validates source jar, javadoc jar, and artifact signing configuration.
+This produces and signs:
+- `danube-client-proto-0.2.0.jar` + sources + javadoc
+- `danube-client-0.2.0.jar` + sources + javadoc
 
-## 3) Publish snapshot
+---
+
+## 5) Publish release version
+
+1. Confirm root `pom.xml` version is `0.2.0` (no `-SNAPSHOT` suffix).
+2. Commit and tag the release:
+
+```bash
+git add -A
+git commit -m "release: v0.2.0"
+git tag v0.2.0
+git push origin main --tags
+```
+
+3. Deploy to Maven Central:
 
 ```bash
 mvn -Prelease -DskipTests deploy
 ```
 
-For `-SNAPSHOT` versions this publishes to:
+Both `danube-client-proto` and `danube-client` are published in one command (multi-module build).
+The `central-publishing-maven-plugin` uploads, validates, and releases automatically
+(`autoPublish=true`, `waitUntil=published`). Artifacts are typically searchable within 30 minutes.
+
+If GPG passphrase entry is required during deployment:
+
+```bash
+mvn -Prelease -DskipTests -Dgpg.passphrase=YOUR_PASSPHRASE deploy
+```
 
-- `https://s01.oss.sonatype.org/content/repositories/snapshots`
+---
 
-## 4) Publish release version
+## 6) After release
 
-1. Update root `<version>` from `x.y.z-SNAPSHOT` to `x.y.z`.
-2. Commit and tag the release.
-3. Run:
+1. Bump to the next development version:
 
 ```bash
-mvn -Prelease -DskipTests deploy
+# In pom.xml, danube-client/pom.xml, danube-client-proto/pom.xml
+# Change version: 0.2.0 → 0.3.0-SNAPSHOT
+```
+
+2. Commit and push:
+
+```bash
+git add -A
+git commit -m "chore: bump to 0.3.0-SNAPSHOT"
+git push origin main
 ```
 
-Release artifacts are staged and closed/released automatically via `nexus-staging-maven-plugin`.
+---
+
+## CI/CD (GitHub Actions)
 
-## 5) After release
+To automate publishing from CI, set these repository secrets:
 
-1. Bump to next development version (e.g. `x.y.(z+1)-SNAPSHOT`).
-2. Push commit and tag.
+| Secret | Value |
+|--------|-------|
+| `CENTRAL_TOKEN_USERNAME` | Portal user token username |
+| `CENTRAL_TOKEN_PASSWORD` | Portal user token password |
+| `GPG_PRIVATE_KEY` | Output of `gpg --armor --export-secret-keys <KEY_ID>` |
+| `GPG_PASSPHRASE` | GPG key passphrase |
+
+Then in your workflow:
+
+```yaml
+- name: Import GPG key
+  run: echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --batch --import
+
+- name: Publish to Maven Central
+  run: mvn -Prelease -DskipTests -Dgpg.passphrase=${{ secrets.GPG_PASSPHRASE }} deploy
+  env:
+    CENTRAL_TOKEN_USERNAME: ${{ secrets.CENTRAL_TOKEN_USERNAME }}
+    CENTRAL_TOKEN_PASSWORD: ${{ secrets.CENTRAL_TOKEN_PASSWORD }}
+```

danube-client-proto/pom.xml

@@ -5,7 +5,7 @@
   <modelVersion>4.0.0</modelVersion>
 
   <parent>
-    <groupId>com.danubemessaging</groupId>
+    <groupId>com.danube-messaging</groupId>
     <artifactId>danube-java</artifactId>
     <version>0.2.0</version>
     <relativePath>../pom.xml</relativePath>

danube-client/pom.xml

@@ -5,7 +5,7 @@
   <modelVersion>4.0.0</modelVersion>
 
   <parent>
-    <groupId>com.danubemessaging</groupId>
+    <groupId>com.danube-messaging</groupId>
     <artifactId>danube-java</artifactId>
     <version>0.2.0</version>
     <relativePath>../pom.xml</relativePath>
@@ -17,7 +17,7 @@
 
   <dependencies>
     <dependency>
-      <groupId>com.danubemessaging</groupId>
+      <groupId>com.danube-messaging</groupId>
       <artifactId>danube-client-proto</artifactId>
       <version>${project.version}</version>
     </dependency>

danube-client/src/main/java/com/danubemessaging/client/Consumer.java

@@ -18,7 +18,13 @@
 import java.util.concurrent.atomic.AtomicReference;
 
 /**
- * Receives messages from a Danube topic and manages per-partition consumers.
+ * Receives messages from a Danube topic.
+ *
+ * <p>Obtain an instance via {@link DanubeClient#newConsumer()}. Call {@link #subscribe()} to
+ * register with the broker, then call {@link #receive()} to get the message stream.
+ * Acknowledge each message with {@link #ack(StreamMessage)} to advance the subscription cursor.
+ *
+ * <p>This class is thread-safe.
  */
 public final class Consumer implements AutoCloseable {
     private enum LifecycleState {
@@ -42,14 +48,32 @@ private enum LifecycleState {
         this.options = Objects.requireNonNull(options, "options");
     }
 
+    /**
+     * Returns the options this consumer was built with.
+     *
+     * @return the consumer options
+     */
     public ConsumerOptions options() {
         return options;
     }
 
+    /**
+     * Subscribes to the topic asynchronously.
+     * Equivalent to calling {@link #subscribe()} on the IO executor.
+     *
+     * @return a future that completes when the subscription is established
+     */
     public CompletableFuture<Void> subscribeAsync() {
         return CompletableFuture.runAsync(this::subscribe, client.ioExecutor());
     }
 
+    /**
+     * Subscribes to the topic and starts the background receive loop.
+     * Must be called before {@link #receive()}.
+     * Idempotent — calling twice on an already-subscribed consumer is a no-op.
+     *
+     * @throws com.danubemessaging.client.errors.DanubeClientException if subscription fails
+     */
     public synchronized void subscribe() {
         ensureOpen();
 
@@ -103,14 +127,35 @@ public synchronized void subscribe() {
         }
     }
 
+    /**
+     * Returns a {@link Flow.Publisher} that emits incoming {@link StreamMessage} objects.
+     * Subscribe to this publisher with a {@link Flow.Subscriber} to process messages.
+     * The publisher completes exceptionally if the receive loop encounters a fatal error.
+     *
+     * @return the message publisher for this consumer
+     */
     public Flow.Publisher<StreamMessage> receive() {
         return publisher;
     }
 
+    /**
+     * Acknowledges a message asynchronously.
+     *
+     * @param message the message to acknowledge
+     * @return a future that completes when the ack is sent
+     */
     public CompletableFuture<Void> ackAsync(StreamMessage message) {
         return CompletableFuture.runAsync(() -> ack(message), client.ioExecutor());
     }
 
+    /**
+     * Acknowledges a message, advancing the subscription cursor past it.
+     * Must be called for each message to prevent redelivery.
+     *
+     * @param message the message to acknowledge; must not be null
+     * @throws com.danubemessaging.client.errors.DanubeClientException if the message's topic
+     *         has no associated consumer or the consumer is closed
+     */
     public void ack(StreamMessage message) {
         ensureOpen();
 
@@ -128,6 +173,10 @@ public void ack(StreamMessage message) {
         notifyMessageAcked(topicConsumer, message);
     }
 
+    /**
+     * Closes this consumer, cancels the receive loop, and releases all resources.
+     * Idempotent — safe to call multiple times.
+     */
     @Override
     public synchronized void close() {
         if (lifecycleState.get() == LifecycleState.CLOSED) {