aljaz/turso
1
0
Fork 0
mirror of https://github.com/aljazceru/turso.git synced 2026-02-16 13:34:33 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add javadoc on classes and public methods for publishing to maven central

Browse Source
This commit is contained in:
Kim Seon Woo
2025-10-07 23:33:02 +09:00
parent f78103cafa
commit 76af79c4fa
12 changed files with 126 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
.github/data/limbo-cargo-output.txt vendored
View File

@@ -1,222 +0,0 @@
Benchmarking limbo/Prepare statement: 'SELECT 1'
Benchmarking limbo/Prepare statement: 'SELECT 1': Warming up for 3.0000 s
Benchmarking limbo/Prepare statement: 'SELECT 1': Collecting 100 samples in estimated 5.0062 s (2.4M iterations)
Benchmarking limbo/Prepare statement: 'SELECT 1': Analyzing
limbo/Prepare statement: 'SELECT 1'
time: [2.0631 µs 2.0688 µs 2.0763 µs]
thrpt: [481.63 Kelem/s 483.37 Kelem/s 484.70 Kelem/s]
Found 13 outliers among 100 measurements (13.00%)
1 (1.00%) low severe
5 (5.00%) high mild
7 (7.00%) high severe
Benchmarking limbo/Prepare statement: 'SELECT * FROM users LIMIT 1'
Benchmarking limbo/Prepare statement: 'SELECT * FROM users LIMIT 1': Warming up for 3.0000 s
Benchmarking limbo/Prepare statement: 'SELECT * FROM users LIMIT 1': Collecting 100 samples in estimated 5.0159 s (1.3M iterations)
Benchmarking limbo/Prepare statement: 'SELECT * FROM users LIMIT 1': Analyzing
limbo/Prepare statement: 'SELECT * FROM users LIMIT 1'
time: [3.9747 µs 3.9842 µs 3.9937 µs]
thrpt: [250.39 Kelem/s 250.99 Kelem/s 251.59 Kelem/s]
Found 17 outliers among 100 measurements (17.00%)
5 (5.00%) low severe
3 (3.00%) low mild
3 (3.00%) high mild
6 (6.00%) high severe
Benchmarking limbo/Prepare statement: 'SELECT first_name, count(1) FROM users GROUP BY first_name HAVING count(1)...
Benchmarking limbo/Prepare statement: 'SELECT first_name, count(1) FROM users GROUP BY first_name HAVING count(1)...: Warming up for 3.0000 s
Benchmarking limbo/Prepare statement: 'SELECT first_name, count(1) FROM users GROUP BY first_name HAVING count(1)...: Collecting 100 samples in estimated 5.0099 s (500k iterations)
Benchmarking limbo/Prepare statement: 'SELECT first_name, count(1) FROM users GROUP BY first_name HAVING count(1)...: Analyzing
limbo/Prepare statement: 'SELECT first_name, count(1) FROM users GROUP BY first_name HAVING count(1)...
time: [10.220 µs 10.280 µs 10.358 µs]
thrpt: [96.544 Kelem/s 97.281 Kelem/s 97.846 Kelem/s]
Found 13 outliers among 100 measurements (13.00%)
1 (1.00%) low severe
2 (2.00%) high mild
10 (10.00%) high severe
Benchmarking limbo/Execute prepared statement: 'SELECT 1'
Benchmarking limbo/Execute prepared statement: 'SELECT 1': Warming up for 3.0000 s
Benchmarking limbo/Execute prepared statement: 'SELECT 1': Collecting 100 samples in estimated 5.0006 s (27M iterations)
Benchmarking limbo/Execute prepared statement: 'SELECT 1': Analyzing
limbo/Execute prepared statement: 'SELECT 1'
time: [181.95 ns 182.33 ns 182.70 ns]
thrpt: [5.4736 Melem/s 5.4844 Melem/s 5.4960 Melem/s]
Found 18 outliers among 100 measurements (18.00%)
6 (6.00%) low severe
3 (3.00%) low mild
6 (6.00%) high mild
3 (3.00%) high severe
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 1'
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 1': Warming up for 3.0000 s
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 1': Collecting 100 samples in estimated 5.0008 s (4.0M iterations)
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 1': Analyzing
limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 1'
time: [1.2549 µs 1.2572 µs 1.2594 µs]
thrpt: [794.03 Kelem/s 795.44 Kelem/s 796.89 Kelem/s]
Found 15 outliers among 100 measurements (15.00%)
6 (6.00%) low severe
3 (3.00%) high mild
6 (6.00%) high severe
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 100'
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 100': Warming up for 3.0000 s
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 100': Collecting 100 samples in estimated 5.0047 s (4.0M iterations)
Benchmarking limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 100': Analyzing
limbo/Execute prepared statement: 'SELECT * FROM users LIMIT 100'
time: [1.2503 µs 1.2528 µs 1.2560 µs]
thrpt: [796.20 Kelem/s 798.23 Kelem/s 799.84 Kelem/s]
Found 14 outliers among 100 measurements (14.00%)
2 (2.00%) low severe
1 (1.00%) low mild
5 (5.00%) high mild
6 (6.00%) high severe
Benchmarking rusqlite/Prepare statement: 'SELECT 1'
Benchmarking rusqlite/Prepare statement: 'SELECT 1': Warming up for 3.0000 s
Benchmarking rusqlite/Prepare statement: 'SELECT 1': Collecting 100 samples in estimated 5.0010 s (6.5M iterations)
Benchmarking rusqlite/Prepare statement: 'SELECT 1': Analyzing
rusqlite/Prepare statement: 'SELECT 1'
time: [768.58 ns 770.50 ns 772.43 ns]
thrpt: [1.2946 Melem/s 1.2979 Melem/s 1.3011 Melem/s]
Found 16 outliers among 100 measurements (16.00%)
5 (5.00%) low severe
2 (2.00%) low mild
1 (1.00%) high mild
8 (8.00%) high severe
Benchmarking rusqlite/Prepare statement: 'SELECT * FROM users LIMIT 1'
Benchmarking rusqlite/Prepare statement: 'SELECT * FROM users LIMIT 1': Warming up for 3.0000 s
Benchmarking rusqlite/Prepare statement: 'SELECT * FROM users LIMIT 1': Collecting 100 samples in estimated 5.0083 s (1.6M iterations)
Benchmarking rusqlite/Prepare statement: 'SELECT * FROM users LIMIT 1': Analyzing
rusqlite/Prepare statement: 'SELECT * FROM users LIMIT 1'
time: [3.2006 µs 3.2038 µs 3.2084 µs]
thrpt: [311.68 Kelem/s 312.13 Kelem/s 312.45 Kelem/s]
Found 11 outliers among 100 measurements (11.00%)
5 (5.00%) low severe
1 (1.00%) low mild
2 (2.00%) high mild
3 (3.00%) high severe
Benchmarking rusqlite/Execute prepared statement: 'SELECT 1'
Benchmarking rusqlite/Execute prepared statement: 'SELECT 1': Warming up for 3.0000 s
Benchmarking rusqlite/Execute prepared statement: 'SELECT 1': Collecting 100 samples in estimated 5.0002 s (82M iterations)
Benchmarking rusqlite/Execute prepared statement: 'SELECT 1': Analyzing
rusqlite/Execute prepared statement: 'SELECT 1'
time: [60.613 ns 60.788 ns 61.098 ns]
thrpt: [16.367 Melem/s 16.451 Melem/s 16.498 Melem/s]
Found 8 outliers among 100 measurements (8.00%)
1 (1.00%) low mild
1 (1.00%) high mild
6 (6.00%) high severe
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 1'
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 1': Warming up for 3.0000 s
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 1': Collecting 100 samples in estimated 5.0014 s (4.3M iterations)
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 1': Analyzing
rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 1'
time: [1.1686 µs 1.1702 µs 1.1716 µs]
thrpt: [853.52 Kelem/s 854.55 Kelem/s 855.74 Kelem/s]
Found 13 outliers among 100 measurements (13.00%)
2 (2.00%) low severe
1 (1.00%) low mild
6 (6.00%) high mild
4 (4.00%) high severe
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 100'
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 100': Warming up for 3.0000 s
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 100': Collecting 100 samples in estimated 5.0016 s (4.3M iterations)
Benchmarking rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 100': Analyzing
rusqlite/Execute prepared statement: 'SELECT * FROM users LIMIT 100'
time: [1.1643 µs 1.1710 µs 1.1789 µs]
thrpt: [848.26 Kelem/s 853.98 Kelem/s 858.85 Kelem/s]
Found 17 outliers among 100 measurements (17.00%)
5 (5.00%) low severe
3 (3.00%) low mild
4 (4.00%) high mild
5 (5.00%) high severe
Running unittests src/lib.rs (target/release/deps/limbo_ext-8b70654a7fccf221)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/lib.rs (target/release/deps/limbo_libsql-66ab9a0ee1a27f4c)
running 1 test
test params::tests::test_serialize_array ... ignored
test result: ok. 0 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/lib.rs (target/release/deps/limbo_macros-669ce5abb31e687e)
Running unittests main.rs (target/release/deps/limbo_sim-d28081335520ff9c)
running 0 tests
Running unittests src/lib.rs (target/release/deps/limbo_sqlite3-1d7f53c447b1fc8a)
Running unittests src/lib.rs (target/release/deps/limbo_uuid-c0d9c3b2e9e30eee)
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/lib.rs (target/release/deps/_limbo-9562557e55b9bbed)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/lib.rs (target/release/deps/sqlite3_parser-475bbf4de217f28a)
running 38 tests
test lexer::sql::test::alter_add_column_primary_key ... ignored
test lexer::sql::test::alter_add_column_unique ... ignored
test lexer::sql::test::alter_rename_same ... ignored
test lexer::sql::test::cast_without_typename ... ignored
test lexer::sql::test::column_specified_more_than_once ... ignored
test lexer::sql::test::count_named_placeholders ... ignored
test lexer::sql::test::count_numbered_placeholders ... ignored
test lexer::sql::test::count_placeholders ... ignored
test lexer::sql::test::count_unused_placeholders ... ignored
test lexer::sql::test::create_strict_table_generated_column ... ignored
test lexer::sql::test::create_strict_table_missing_datatype ... ignored
test lexer::sql::test::create_strict_table_unknown_datatype ... ignored
test lexer::sql::test::create_table_with_only_generated_column ... ignored
test lexer::sql::test::create_table_without_column ... ignored
test lexer::sql::test::create_table_without_rowid_missing_pk ... ignored
test lexer::sql::test::create_temporary_table_with_qualified_name ... ignored
test lexer::sql::test::create_view_duplicate_column_name ... ignored
Running benches/keyword.rs (target/release/deps/keyword-255a8492c4f11233)
test lexer::sql::test::create_view_mismatch_count ... ignored
test lexer::sql::test::delete_order_by_without_limit ... ignored
test lexer::sql::test::duplicate_column ... ignored
test lexer::sql::test::extra_comments_between_statements ... ignored
test lexer::sql::test::extra_semicolons_between_statements ... ignored
test lexer::sql::test::foreign_key_on_column ... ignored
test lexer::sql::test::indexed_by_clause_within_triggers ... ignored
test lexer::sql::test::insert_default_values ... ignored
test lexer::sql::test::insert_mismatch_count ... ignored
test lexer::sql::test::missing_join_clause ... ignored
test lexer::sql::test::natural_join_on ... ignored
test lexer::sql::test::only_semicolons_no_statements ... ignored
test lexer::sql::test::qualified_table_name_within_triggers ... ignored
test lexer::sql::test::selects_compound_mismatch_columns_count ... ignored
test lexer::sql::test::unknown_table_option ... ignored
test lexer::sql::test::update_order_by_without_limit ... ignored
test lexer::sql::test::values_mismatch_columns_count ... ignored
test lexer::sql::test::vtab_args ... ignored
test lexer::sql::tests::fallible_iterator ... ignored
test lexer::sql::tests::invalid_number_literal ... ignored
test parser::ast::test::test_dequote ... ignored
test result: ok. 0 passed; 0 failed; 38 ignored; 0 measured; 0 filtered out; finished in 0.00s
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

1
bindings/java/.gitignore vendored
View File

@@ -41,3 +41,4 @@ bin/
### turso builds ###
libs
temp

11
bindings/java/src/main/java/tech/turso/JDBC.java
View File

@@ -10,6 +10,9 @@ import tech.turso.jdbc4.JDBC4Connection;
import tech.turso.utils.Logger;
import tech.turso.utils.LoggerFactory;
/**
* Turso JDBC driver implementation.
*/
public final class JDBC implements Driver {
private static final Logger logger = LoggerFactory.getLogger(JDBC.class);
@@ -24,6 +27,14 @@ public final class JDBC implements Driver {
}
}
/**
* Creates a new Turso JDBC connection.
*
* @param url the database URL
* @param properties connection properties
* @return a new connection instance, or null if the URL is not valid
* @throws SQLException if a database access error occurs
*/
@Nullable
public static JDBC4Connection createConnection(String url, Properties properties)
throws SQLException {

2
bindings/java/src/main/java/tech/turso/core/TursoDBFactory.java
View File

@@ -23,7 +23,7 @@ public final class TursoDBFactory {
* @param url the URL of the database
* @param filePath the path to the database file
* @param properties additional properties for the database connection
* @return an instance of {@link tursoDB}
* @return an instance of {@link TursoDB}
* @throws SQLException if there is an error opening the connection
* @throws IllegalArgumentException if the fileName is empty
*/

5
bindings/java/src/main/java/tech/turso/core/TursoResultSet.java
View File

@@ -57,7 +57,7 @@ public final class TursoResultSet {
}
/**
* Moves the cursor forward one row from its current position. A {@link tursoResultSet} cursor is
* Moves the cursor forward one row from its current position. A {@link TursoResultSet} cursor is
* initially positioned before the first fow; the first call to the method <code>next</code> makes
* the first row the current row; the second call makes the second row the current row, and so on.
* When a call to the <code>next</code> method returns <code>false</code>, the cursor is
@@ -65,6 +65,9 @@ public final class TursoResultSet {
*
* <p>Note that turso only supports <code>ResultSet.TYPE_FORWARD_ONLY</code>, which means that the
* cursor can only move forward.
*
* @return true if the new current row is valid; false if there are no more rows
* @throws SQLException if a database access error occurs
*/
public boolean next() throws SQLException {
if (!open) {

4
bindings/java/src/main/java/tech/turso/core/TursoStatement.java
View File

@@ -91,8 +91,8 @@ public final class TursoStatement {
private native void _close(long statementPointer);
/**
* Initializes the column metadata, such as the names of the columns. Since {@link tursoStatement}
* can only have a single {@link tursoResultSet}, it is appropriate to place the initialization of
* Initializes the column metadata, such as the names of the columns. Since {@link TursoStatement}
* can only have a single {@link TursoResultSet}, it is appropriate to place the initialization of
* column metadata here.
*
* @throws SQLException if a database access error occurs while retrieving column names

40
bindings/java/src/main/java/tech/turso/jdbc4/JDBC4Connection.java
View File

@@ -9,20 +9,45 @@ import tech.turso.annotations.SkipNullableCheck;
import tech.turso.core.TursoConnection;
import tech.turso.core.TursoStatement;
/**
* JDBC 4 Connection implementation for Turso databases.
*/
public final class JDBC4Connection implements Connection {
private final TursoConnection connection;
private Map<String, Class<?>> typeMap = new HashMap<>();
/**
* Creates a new JDBC4 connection.
*
* @param url the database URL
* @param filePath the database file path
* @throws SQLException if a database access error occurs
*/
public JDBC4Connection(String url, String filePath) throws SQLException {
this.connection = new TursoConnection(url, filePath);
}
/**
* Creates a new JDBC4 connection with properties.
*
* @param url the database URL
* @param filePath the database file path
* @param properties connection properties
* @throws SQLException if a database access error occurs
*/
public JDBC4Connection(String url, String filePath, Properties properties) throws SQLException {
this.connection = new TursoConnection(url, filePath, properties);
}
/**
* Prepares a SQL statement for execution.
*
* @param sql the SQL statement to prepare
* @return the prepared statement
* @throws SQLException if a database access error occurs
*/
public TursoStatement prepare(String sql) throws SQLException {
final TursoStatement statement = connection.prepare(sql);
statement.initializeColumnMetadata();
@@ -357,6 +382,11 @@ public final class JDBC4Connection implements Connection {
return false;
}
/**
* Sets the busy timeout for the connection.
*
* @param busyTimeout the timeout in milliseconds
*/
public void setBusyTimeout(int busyTimeout) {
// TODO: add support for busy timeout
}
@@ -367,10 +397,20 @@ public final class JDBC4Connection implements Connection {
return 0;
}
/**
* Gets the database URL.
*
* @return the database URL
*/
public String getUrl() {
return this.connection.getUrl();
}
/**
* Checks if the connection is open.
*
* @throws SQLException if the connection is closed
*/
public void checkOpen() throws SQLException {
connection.checkOpen();
}

8
bindings/java/src/main/java/tech/turso/jdbc4/JDBC4DatabaseMetaData.java
View File

@@ -13,6 +13,9 @@ import tech.turso.core.TursoPropertiesHolder;
import tech.turso.utils.Logger;
import tech.turso.utils.LoggerFactory;
/**
* JDBC 4 DatabaseMetaData implementation for Turso databases.
*/
public final class JDBC4DatabaseMetaData implements DatabaseMetaData {
private static final Logger logger = LoggerFactory.getLogger(JDBC4DatabaseMetaData.class);
@@ -51,6 +54,11 @@ public final class JDBC4DatabaseMetaData implements DatabaseMetaData {
@Nullable private PreparedStatement getColumnPrivileges = null;
/**
* Creates a new JDBC4DatabaseMetaData instance.
*
* @param connection the database connection
*/
public JDBC4DatabaseMetaData(JDBC4Connection connection) {
this.connection = connection;
}

10
bindings/java/src/main/java/tech/turso/jdbc4/JDBC4PreparedStatement.java
View File

@@ -26,11 +26,21 @@ import java.util.Calendar;
import tech.turso.annotations.SkipNullableCheck;
import tech.turso.core.TursoResultSet;
/**
* JDBC 4 PreparedStatement implementation for Turso databases.
*/
public final class JDBC4PreparedStatement extends JDBC4Statement implements PreparedStatement {
private final String sql;
private final JDBC4ResultSet resultSet;
/**
* Creates a new JDBC4PreparedStatement.
*
* @param connection the database connection
* @param sql the SQL statement to prepare
* @throws SQLException if a database access error occurs
*/
public JDBC4PreparedStatement(JDBC4Connection connection, String sql) throws SQLException {
super(connection);
this.sql = sql;

19
bindings/java/src/main/java/tech/turso/jdbc4/JDBC4ResultSet.java
View File

@@ -27,10 +27,18 @@ import tech.turso.annotations.Nullable;
import tech.turso.annotations.SkipNullableCheck;
import tech.turso.core.TursoResultSet;
/**
* JDBC 4 ResultSet implementation for Turso databases.
*/
public final class JDBC4ResultSet implements ResultSet, ResultSetMetaData {
private final TursoResultSet resultSet;
/**
* Creates a new JDBC4ResultSet.
*
* @param resultSet the underlying Turso result set
*/
public JDBC4ResultSet(TursoResultSet resultSet) {
this.resultSet = resultSet;
}
@@ -1279,8 +1287,19 @@ public final class JDBC4ResultSet implements ResultSet, ResultSetMetaData {
throw new UnsupportedOperationException("not implemented");
}
/**
* Functional interface for result set value suppliers.
*
* @param <T> the type of value to supply
*/
@FunctionalInterface
public interface ResultSetSupplier<T> {
/**
* Gets a result from the result set.
*
* @return the result value
* @throws Exception if an error occurs
*/
T get() throws Exception;
}

17
bindings/java/src/main/java/tech/turso/jdbc4/JDBC4Statement.java
View File

@@ -17,6 +17,9 @@ import tech.turso.annotations.SkipNullableCheck;
import tech.turso.core.TursoResultSet;
import tech.turso.core.TursoStatement;
/**
* JDBC 4 Statement implementation for Turso databases.
*/
public class JDBC4Statement implements Statement {
private static final Pattern BATCH_COMPATIBLE_PATTERN =
@@ -35,7 +38,10 @@ public class JDBC4Statement implements Statement {
private final JDBC4Connection connection;
/** The underlying Turso statement. */
@Nullable protected TursoStatement statement = null;
/** The number of rows affected by the last update operation. */
protected long updateCount;
// Because JDBC4Statement has different life cycle in compared to tursoStatement, let's use this
@@ -475,8 +481,19 @@ public class JDBC4Statement implements Statement {
}
}
/**
* Functional interface for SQL callable operations.
*
* @param <T> the return type
*/
@FunctionalInterface
protected interface SQLCallable<T> {
/**
* Executes the SQL operation.
*
* @return the result of the operation
* @throws SQLException if a database access error occurs
*/
T call() throws SQLException;
}

13
bindings/java/src/main/java/tech/turso/utils/ByteArrayUtils.java
View File

@@ -3,7 +3,14 @@ package tech.turso.utils;
import java.nio.charset.StandardCharsets;
import tech.turso.annotations.Nullable;
/** Utility class for converting between byte arrays and strings using UTF-8 encoding. */
public final class ByteArrayUtils {
/**
* Converts a UTF-8 encoded byte array to a string.
*
* @param buffer the byte array to convert, may be null
* @return the string representation, or null if the input is null
*/
@Nullable
public static String utf8ByteBufferToString(@Nullable byte[] buffer) {
if (buffer == null) {
@@ -13,6 +20,12 @@ public final class ByteArrayUtils {
return new String(buffer, StandardCharsets.UTF_8);
}
/**
* Converts a string to a UTF-8 encoded byte array.
*
* @param str the string to convert, may be null
* @return the byte array representation, or null if the input is null
*/
@Nullable
public static byte[] stringToUtf8ByteArray(@Nullable String str) {
if (str == null) {