Add provider JDBC helpers

Author: esasmer-dou

README.md

@@ -31,7 +31,7 @@ Use the official Dubbo stack instead when you need full Dubbo governance, config
 <dependency>
   <groupId>com.reactor</groupId>
   <artifactId>java-rust-dubbo</artifactId>
-  <version>0.2.1</version>
+  <version>0.2.2</version>
 </dependency>
 ```
 
@@ -77,7 +77,7 @@ For the smallest static-provider native setup, use the `native-static` classifie
 <dependency>
   <groupId>com.reactor</groupId>
   <artifactId>java-rust-dubbo</artifactId>
-  <version>0.2.1</version>
+  <version>0.2.2</version>
   <classifier>native-static</classifier>
 </dependency>
 ```
@@ -112,6 +112,8 @@ Common provider classes:
 - `DubboProviderSupport`
 - `PlainDubboProvider`
 - `ZookeeperDubboProviderRegistration`
+- `com.reactor.rust.dubbo.provider.jdbc.JdbcRepository`
+- `com.reactor.rust.dubbo.provider.jdbc.HikariDataSources`
 
 Classes under `com.reactor.rust.dubbo.internal.*` are implementation details. They are separated by responsibility so the runtime is easier to maintain:
 
@@ -157,6 +159,11 @@ List<DubboProviderSupport.ExportedService<?>> exported =
 BEST: keep the service list explicit and move only duplicated lifecycle code to these helpers.
 ANTI-PATTERN: adding an automatic provider scanner that exports every interface on the classpath.
 
+Provider-side DB helpers are optional. Use them when a plain Dubbo provider needs the same
+low-boilerplate JDBC/Hikari lifecycle pattern as the sample provider. They do not generate SQL and
+they do not map rows automatically. Your provider still owns SQL, indexes, row mapping, transaction
+boundaries, and write idempotency.
+
 ## Quick Start
 
 This section shows the complete flow for adding a Dubbo consumer to a Java/Rust REST application.
@@ -498,12 +505,12 @@ mvn clean verify
 
 Release artifacts are produced under `target/`:
 
-- `java-rust-dubbo-0.2.1.jar`
-- `java-rust-dubbo-0.2.1-native-static.jar`
-- `java-rust-dubbo-0.2.1-sources.jar`
+- `java-rust-dubbo-0.2.2.jar`
+- `java-rust-dubbo-0.2.2-native-static.jar`
+- `java-rust-dubbo-0.2.2-sources.jar`
 
 ## Documentation
 
 - [Production Guide](docs/PRODUCTION_GUIDE.md)
-- [Release Notes](docs/RELEASE_NOTES_v0.2.1.md)
+- [Release Notes](docs/RELEASE_NOTES_v0.2.2.md)
 - [Turkish README](README.tr.md)

README.tr.md

@@ -36,7 +36,7 @@ Bu kütüphane, "dependency ekleyince her şeyi otomatik yapsın" yaklaşımınd
 <dependency>
   <groupId>com.reactor</groupId>
   <artifactId>java-rust-dubbo</artifactId>
-  <version>0.2.1</version>
+  <version>0.2.2</version>
 </dependency>
 ```
 
@@ -82,7 +82,7 @@ En küçük static-provider native kurulum için full JAR yerine `native-static`
 <dependency>
   <groupId>com.reactor</groupId>
   <artifactId>java-rust-dubbo</artifactId>
-  <version>0.2.1</version>
+  <version>0.2.2</version>
   <classifier>native-static</classifier>
 </dependency>
 ```
@@ -117,6 +117,8 @@ Sık kullanılan provider sınıfları:
 - `DubboProviderSupport`
 - `PlainDubboProvider`
 - `ZookeeperDubboProviderRegistration`
+- `com.reactor.rust.dubbo.provider.jdbc.JdbcRepository`
+- `com.reactor.rust.dubbo.provider.jdbc.HikariDataSources`
 
 `com.reactor.rust.dubbo.internal.*` altındaki sınıflar kütüphanenin iç uygulama detaylarıdır. Bu paketler sorumluluklarına göre ayrılmıştır:
 
@@ -162,6 +164,11 @@ List<DubboProviderSupport.ExportedService<?>> exported =
 BEST: servis listesini explicit tutun, sadece tekrar eden lifecycle kodunu bu yardımcı sınıflara
 taşıyın. ANTI-PATTERN: classpath'teki her interface'i otomatik export eden gizli scanner eklemek.
 
+Provider tarafındaki DB yardımcıları opsiyoneldir. Plain Dubbo provider aynı sample provider gibi
+düşük boilerplate JDBC/Hikari lifecycle kalıbı istiyorsa kullanılmalıdır. Bu sınıflar SQL üretmez ve
+row mapping'i otomatik tahmin etmez. SQL, index, row mapping, transaction sınırı ve write idempotency
+kararı provider uygulamasında kalır.
+
 ## Hızlı Başlangıç
 
 Bu bölüm, bir Java/Rust REST uygulamasını adım adım Dubbo consumer haline getirir.
@@ -497,6 +504,6 @@ mvn clean verify
 
 Üretilen paketler:
 
-- `target/java-rust-dubbo-0.2.1.jar`
-- `target/java-rust-dubbo-0.2.1-native-static.jar`
-- `target/java-rust-dubbo-0.2.1-sources.jar`
+- `target/java-rust-dubbo-0.2.2.jar`
+- `target/java-rust-dubbo-0.2.2-native-static.jar`
+- `target/java-rust-dubbo-0.2.2-sources.jar`

docs/RELEASE_NOTES_v0.2.2.md

@@ -0,0 +1,34 @@
+# java-rust-dubbo 0.2.2
+
+`0.2.2` keeps the native Dubbo behavior unchanged and adds optional provider-side JDBC helpers for
+plain Java Dubbo providers.
+
+## What Changed For Users
+
+- `com.reactor.rust.dubbo.provider.jdbc.JdbcRepository` is available for repeated JDBC
+  connection/query/lifecycle code.
+- `com.reactor.rust.dubbo.provider.jdbc.HikariDataSources` can create a Hikari pool from
+  `sample.db.*`-style properties.
+- Hikari is optional. Static/catalog-only providers do not need to load it.
+- Provider SQL and row mapping stay explicit in application code.
+- Existing consumer APIs and native response handle paths are unchanged.
+
+## Provider Example
+
+```java
+public final class CustomerRepository extends JdbcRepository {
+    private CustomerRepository(Properties properties) {
+        super(HikariDataSources.create(properties, "sample.db"), true);
+    }
+
+    public List<Customer> findCustomers() {
+        return query("Find customers", SQL, SqlBinder.none(), CustomerRepository::toCustomer);
+    }
+}
+```
+
+## Compatibility Notes
+
+- Native ABI did not change.
+- `0.2.1` applications can upgrade without changing Dubbo consumer call paths.
+- Provider DB helpers are additive. They are not required for non-DB providers.

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>com.reactor</groupId>
   <artifactId>java-rust-dubbo</artifactId>
-  <version>0.2.1</version>
+  <version>0.2.2</version>
   <packaging>jar</packaging>
 
   <name>java-rust-dubbo</name>
@@ -28,6 +28,7 @@
     <netty.version>4.2.1.Final</netty.version>
     <zookeeper.version>3.7.2</zookeeper.version>
     <slf4j.version>1.7.35</slf4j.version>
+    <hikaricp.version>5.1.0</hikaricp.version>
     <junit.version>5.11.4</junit.version>
   </properties>
 
@@ -47,6 +48,12 @@
   </dependencyManagement>
 
   <dependencies>
+    <dependency>
+      <groupId>com.zaxxer</groupId>
+      <artifactId>HikariCP</artifactId>
+      <version>${hikaricp.version}</version>
+      <optional>true</optional>
+    </dependency>
     <dependency>
       <groupId>org.apache.dubbo</groupId>
       <artifactId>dubbo-rpc-dubbo</artifactId>

src/main/java/com/reactor/rust/dubbo/provider/jdbc/HikariDataSources.java

@@ -0,0 +1,98 @@
+package com.reactor.rust.dubbo.provider.jdbc;
+
+import com.zaxxer.hikari.HikariConfig;
+import com.zaxxer.hikari.HikariDataSource;
+
+import java.util.Locale;
+import java.util.Properties;
+
+public final class HikariDataSources {
+
+    private HikariDataSources() {}
+
+    public static HikariDataSource create(Properties properties, String prefix) {
+        String root = requirePrefix(prefix);
+        HikariConfig config = new HikariConfig();
+        config.setPoolName(get(properties, root + ".pool-name"));
+        config.setDriverClassName(get(properties, root + ".driver-class-name"));
+        config.setJdbcUrl(get(properties, root + ".jdbc-url"));
+        config.setUsername(get(properties, root + ".username"));
+        config.setPassword(getOptional(properties, root + ".password"));
+        config.setMaximumPoolSize(getInt(properties, root + ".maximum-pool-size"));
+        config.setMinimumIdle(getInt(properties, root + ".minimum-idle"));
+        config.setConnectionTimeout(getLong(properties, root + ".connection-timeout-ms"));
+        config.setValidationTimeout(getLong(properties, root + ".validation-timeout-ms"));
+        config.setIdleTimeout(getLong(properties, root + ".idle-timeout-ms"));
+        config.setMaxLifetime(getLong(properties, root + ".max-lifetime-ms"));
+        config.setLeakDetectionThreshold(getLong(properties, root + ".leak-detection-threshold-ms"));
+        config.setInitializationFailTimeout(getLong(properties, root + ".initialization-fail-timeout-ms"));
+        config.setAutoCommit(getBoolean(properties, root + ".auto-commit"));
+        config.setReadOnly(getBoolean(properties, root + ".read-only"));
+        config.setRegisterMbeans(getBoolean(properties, root + ".register-mbeans"));
+
+        String applicationName = getOptional(properties, root + ".postgresql.application-name");
+        if (!applicationName.isBlank()) {
+            config.addDataSourceProperty("ApplicationName", applicationName);
+        }
+        return new HikariDataSource(config);
+    }
+
+    private static String get(Properties properties, String key) {
+        String value = getOptional(properties, key);
+        if (value.isBlank()) {
+            throw new IllegalStateException("Missing required JDBC property: " + key);
+        }
+        return value;
+    }
+
+    private static String getOptional(Properties properties, String key) {
+        String value = System.getProperty(key);
+        if (value == null || value.isBlank()) {
+            value = System.getenv(toEnvKey(key));
+        }
+        if ((value == null || value.isBlank()) && properties != null) {
+            value = properties.getProperty(key);
+        }
+        return value == null ? "" : value.trim();
+    }
+
+    private static int getInt(Properties properties, String key) {
+        String value = get(properties, key);
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new IllegalArgumentException("JDBC property must be an integer: " + key + "=" + value, e);
+        }
+    }
+
+    private static long getLong(Properties properties, String key) {
+        String value = get(properties, key);
+        try {
+            return Long.parseLong(value);
+        } catch (NumberFormatException e) {
+            throw new IllegalArgumentException("JDBC property must be a long: " + key + "=" + value, e);
+        }
+    }
+
+    private static boolean getBoolean(Properties properties, String key) {
+        String value = get(properties, key);
+        if ("true".equalsIgnoreCase(value) || "1".equals(value) || "yes".equalsIgnoreCase(value)) {
+            return true;
+        }
+        if ("false".equalsIgnoreCase(value) || "0".equals(value) || "no".equalsIgnoreCase(value)) {
+            return false;
+        }
+        throw new IllegalArgumentException("JDBC property must be a boolean: " + key + "=" + value);
+    }
+
+    private static String requirePrefix(String prefix) {
+        if (prefix == null || prefix.isBlank()) {
+            throw new IllegalArgumentException("prefix must not be blank");
+        }
+        return prefix.trim();
+    }
+
+    private static String toEnvKey(String key) {
+        return key.toUpperCase(Locale.ROOT).replace('.', '_').replace('-', '_');
+    }
+}

src/main/java/com/reactor/rust/dubbo/provider/jdbc/JdbcRepository.java

@@ -0,0 +1,117 @@
+package com.reactor.rust.dubbo.provider.jdbc;
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.sql.PreparedStatement;
+import java.sql.ResultSet;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+
+public abstract class JdbcRepository implements AutoCloseable {
+
+    private final DataSource dataSource;
+    private final boolean schemaInit;
+    private volatile boolean initialized;
+
+    protected JdbcRepository(DataSource dataSource, boolean schemaInit) {
+        this.dataSource = Objects.requireNonNull(dataSource, "dataSource");
+        this.schemaInit = schemaInit;
+    }
+
+    protected final void ensureInitialized() {
+        if (!schemaInit || initialized) {
+            return;
+        }
+        synchronized (this) {
+            if (initialized) {
+                return;
+            }
+            try (Connection connection = dataSource.getConnection()) {
+                initializeSchema(connection);
+                initialized = true;
+            } catch (Exception e) {
+                throw new IllegalStateException("JDBC schema initialization failed", e);
+            }
+        }
+    }
+
+    protected void initializeSchema(Connection connection) throws Exception {
+        // Default: no schema bootstrap.
+    }
+
+    protected final <T> List<T> query(
+            String operation,
+            String sql,
+            SqlBinder binder,
+            RowMapper<T> mapper) {
+        ensureInitialized();
+        try (Connection connection = dataSource.getConnection();
+             PreparedStatement statement = connection.prepareStatement(sql)) {
+            binder.bind(statement);
+            try (ResultSet resultSet = statement.executeQuery()) {
+                List<T> rows = new ArrayList<>();
+                while (resultSet.next()) {
+                    rows.add(mapper.map(resultSet));
+                }
+                return rows;
+            }
+        } catch (Exception e) {
+            throw new IllegalStateException(operation + " failed", e);
+        }
+    }
+
+    protected final <T> T queryOne(
+            String operation,
+            String sql,
+            SqlBinder binder,
+            RowMapper<T> mapper,
+            T emptyValue) {
+        ensureInitialized();
+        try (Connection connection = dataSource.getConnection();
+             PreparedStatement statement = connection.prepareStatement(sql)) {
+            binder.bind(statement);
+            try (ResultSet resultSet = statement.executeQuery()) {
+                return resultSet.next() ? mapper.map(resultSet) : emptyValue;
+            }
+        } catch (Exception e) {
+            throw new IllegalStateException(operation + " failed", e);
+        }
+    }
+
+    protected final int update(String operation, String sql, SqlBinder binder) {
+        ensureInitialized();
+        try (Connection connection = dataSource.getConnection();
+             PreparedStatement statement = connection.prepareStatement(sql)) {
+            binder.bind(statement);
+            return statement.executeUpdate();
+        } catch (Exception e) {
+            throw new IllegalStateException(operation + " failed", e);
+        }
+    }
+
+    @Override
+    public void close() {
+        if (dataSource instanceof AutoCloseable closeable) {
+            try {
+                closeable.close();
+            } catch (Exception e) {
+                throw new IllegalStateException("JDBC datasource close failed", e);
+            }
+        }
+    }
+
+    @FunctionalInterface
+    public interface SqlBinder {
+        void bind(PreparedStatement statement) throws Exception;
+
+        static SqlBinder none() {
+            return statement -> {};
+        }
+    }
+
+    @FunctionalInterface
+    public interface RowMapper<T> {
+        T map(ResultSet row) throws Exception;
+    }
+}