Skip to content

docs: refine GreptimeOption java doc #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fengjiachun merged 1 commit into from
Aug 25, 2025
Merged

docs: refine GreptimeOption java doc #95

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 105 additions & 40 deletions ingester-protocol/src/main/java/io/greptime/options/GreptimeOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,32 +178,60 @@ public static final class Builder {
// The request router
private Router<Void, Endpoint> router;

/**
* Create a new builder with the given endpoints and database.
*
* @param endpoints the endpoints to connect to
* @param database The target database name. Default is "public". When a database name is provided,
* the DB will attempt to parse catalog and schema from it. The format is
* {@code [<catalog>-]<schema>}, where:
* <ul>
* <li>If {@code [<catalog>-]} is not provided, the entire database name is used as schema</li>
* <li>If {@code [<catalog>-]} is provided, the name is split on "-" into catalog and schema</li>
* </ul>
*/
public Builder(List<Endpoint> endpoints, String database) {
this.endpoints.addAll(endpoints);
this.database = database;
}

/**
* Asynchronous thread pool, which is used to handle various asynchronous
* tasks in the SDK (You are using a purely asynchronous SDK). If you do not
* set it, there will be a default implementation, which you can reconfigure
* if the default implementation is not satisfied.
* <p>
* Note: We do not close it to free resources(if it needs to be closed), as we
* view it as shared.
*
* @param asyncPool async thread pool
* Sets the asynchronous thread pool used to handle various asynchronous tasks in the SDK.
* This SDK is purely asynchronous. If not set, a default implementation will be used.
* It's generally recommended to use the default configuration.
*
* <p>Default: {@link io.greptime.common.util.SerializingExecutor} - This executor does not start any additional threads,
* it only uses the current thread to batch process small tasks.
*
* <p>Note: The SDK treats the thread pool as a shared resource and will not actively close it
* to release resources (even if it needs to be closed).
*
* @param asyncPool the asynchronous thread pool to use
* @return this builder
* @see io.greptime.common.util.SerializingExecutor
*/
public Builder asyncPool(Executor asyncPool) {
this.asyncPool = asyncPool;
return this;
}

/**
* Sets the RPC options, in general, the default configuration is fine.
* Sets the RPC options. In general, the default configuration is fine.
*
* <p>This configuration only applies to Regular API, not to Bulk API.
*
* @param rpcOptions the rpc options
* <p>Key parameters include:
* <ul>
* <li>useRpcSharedPool: Whether to use global RPC shared pool (default: false)</li>
* <li>defaultRpcTimeout: RPC request timeout (default: 60000ms)</li>
* <li>maxInboundMessageSize: Maximum inbound message size (default: 256MB)</li>
* <li>flowControlWindow: Flow control window size (default: 256MB)</li>
* <li>idleTimeoutSeconds: Idle timeout duration (default: 5 minutes)</li>
* <li>keepAliveTimeSeconds: Keep-alive ping interval (default: disabled)</li>
* <li>limitKind: gRPC layer concurrency limit algorithm (default: None)</li>
* </ul>
*
* @param rpcOptions the RPC options
* @return this builder
*/
public Builder rpcOptions(RpcOptions rpcOptions) {
Expand All @@ -215,7 +243,15 @@ public Builder rpcOptions(RpcOptions rpcOptions) {
* Set `TlsOptions` to use secure connection between client and server. Set to `null` to use
* plaintext connection instead.
*
* @param tlsOptions for configure secure connection, set to null to use plaintext
* <p>Key parameters include:
* <ul>
* <li>clientCertChain: Client certificate chain file</li>
* <li>privateKey: Private key file</li>
* <li>privateKeyPassword: Private key password</li>
* <li>rootCerts: Root certificate file</li>
* </ul>
*
* @param tlsOptions TLS options for secure connection configuration, set to null to use plaintext
* @return this builder
*/
public Builder tlsOptions(TlsOptions tlsOptions) {
Expand All @@ -224,9 +260,14 @@ public Builder tlsOptions(TlsOptions tlsOptions) {
}

/**
* In some case of failure, a retry of write can be attempted.
* Maximum number of retries for write failures. Whether to retry depends on the error type
* {@link io.greptime.Status#isShouldRetry()}.
*
* <p>This configuration only applies to Regular API, not to Bulk API.
*
* @param maxRetries max retries times
* <p>Default: 1
*
* @param maxRetries the maximum number of retry attempts
* @return this builder
*/
public Builder writeMaxRetries(int maxRetries) {
Expand All @@ -237,7 +278,11 @@ public Builder writeMaxRetries(int maxRetries) {
/**
* Write flow limit: maximum number of data points in-flight.
*
* @param maxInFlightWritePoints max in-flight points
* <p>This configuration only applies to Regular API, not to Bulk API.
*
* <p>Default: 655360 (10 * 65536)
*
* @param maxInFlightWritePoints the maximum number of in-flight write points
* @return this builder
*/
public Builder maxInFlightWritePoints(int maxInFlightWritePoints) {
Expand All @@ -247,15 +292,21 @@ public Builder maxInFlightWritePoints(int maxInFlightWritePoints) {

/**
* Write flow limit: the policy to use when the write flow limit is exceeded.
* The options:
* - `LimitedPolicy.DiscardPolicy`: discard the data if the limiter is full.
* - `LimitedPolicy.AbortPolicy`: abort if the limiter is full.
* - `LimitedPolicy.BlockingPolicy`: blocks if the limiter is full.
* - `LimitedPolicy.AbortOnBlockingTimeoutPolicy`: blocks the specified time if
* the limiter is full, abort if timeout.
* The default is `LimitedPolicy.AbortOnBlockingTimeoutPolicy`
*
* @param writeLimitedPolicy write limited policy
*
* <p>This configuration only applies to Regular API, not to Bulk API.
*
* <p>Available policies:
* <ul>
* <li>{@code DiscardPolicy}: Discard data if limiter is full</li>
* <li>{@code AbortPolicy}: Abort if limiter is full, throw exception</li>
* <li>{@code BlockingPolicy}: Block the write thread if limiter is full</li>
* <li>{@code BlockingTimeoutPolicy}: Block for specified time then proceed if limiter is full</li>
* <li>{@code AbortOnBlockingTimeoutPolicy}: Block for specified time, abort and throw exception if timeout</li>
* </ul>
*
* <p>Default: {@code AbortOnBlockingTimeoutPolicy} (3 seconds)
*
* @param writeLimitedPolicy the write flow control policy
* @return this builder
*/
public Builder writeLimitedPolicy(LimitedPolicy writeLimitedPolicy) {
Expand All @@ -264,11 +315,14 @@ public Builder writeLimitedPolicy(LimitedPolicy writeLimitedPolicy) {
}

/**
* The default rate limit value(points per second) for `StreamWriter`. It only takes
* The default rate limit value (points per second) for `StreamWriter`. It only takes
* effect when we do not specify the `maxPointsPerSecond` when creating a `StreamWriter`.
* The default is 10 * 65536
*
* @param defaultStreamMaxWritePointsPerSecond default max write points per second
* <p>This configuration only applies to Regular API, not to Bulk API.
*
* <p>Default: 655360 (10 * 65536)
*
* @param defaultStreamMaxWritePointsPerSecond the default maximum write points per second for StreamWriter
* @return this builder
*/
public Builder defaultStreamMaxWritePointsPerSecond(int defaultStreamMaxWritePointsPerSecond) {
Expand All @@ -277,9 +331,13 @@ public Builder defaultStreamMaxWritePointsPerSecond(int defaultStreamMaxWritePoi
}

/**
* Use zero copy write in bulk write.
* Whether to use zero-copy optimization in bulk write operations.
*
* @param useZeroCopyWriteInBulkWrite use zero copy write in bulk write
* <p>This configuration is effective for Bulk API.
*
* <p>Default: true
*
* @param useZeroCopyWriteInBulkWrite whether to use zero-copy write optimization in bulk operations
* @return this builder
*/
public Builder useZeroCopyWriteInBulkWrite(boolean useZeroCopyWriteInBulkWrite) {
Expand All @@ -288,10 +346,12 @@ public Builder useZeroCopyWriteInBulkWrite(boolean useZeroCopyWriteInBulkWrite)
}

/**
* Refresh frequency of route tables. The background refreshes all route tables
* periodically. By default, By default, the route tables will not be refreshed.
* Background refresh period for route tables (seconds). The background refreshes all route tables
* periodically. Route tables will not be refreshed if value is <= 0.
*
* <p>Default: 600 (10 minutes)
*
* @param routeTableRefreshPeriodSeconds refresh period for route tables cache
* @param routeTableRefreshPeriodSeconds the refresh period for route tables cache in seconds
* @return this builder
*/
public Builder routeTableRefreshPeriodSeconds(long routeTableRefreshPeriodSeconds) {
Expand All @@ -300,11 +360,13 @@ public Builder routeTableRefreshPeriodSeconds(long routeTableRefreshPeriodSecond
}

/**
* Timeout for health check. The default is 1000ms.
* Timeout for health check operations (milliseconds).
* If the health check is not completed within the specified time, the health
* check will fail.
*
* @param checkHealthTimeoutMs timeout for health check
* <p>Default: 1000 (1 second)
*
* @param checkHealthTimeoutMs the timeout for health check operations in milliseconds
* @return this builder
*/
public Builder checkHealthTimeoutMs(long checkHealthTimeoutMs) {
Expand All @@ -313,10 +375,11 @@ public Builder checkHealthTimeoutMs(long checkHealthTimeoutMs) {
}

/**
* Sets authentication information. If the DB is not required to authenticate,
* we can ignore this.
* Sets database authentication information. Can be ignored if database doesn't require authentication.
*
* <p>Default: null
*
* @param authInfo the authentication information
* @param authInfo the database authentication information
* @return this builder
*/
public Builder authInfo(AuthInfo authInfo) {
Expand All @@ -325,10 +388,12 @@ public Builder authInfo(AuthInfo authInfo) {
}

/**
* Sets the request router. The internal default implementation works well.
* You don't need to set it unless you have special requirements.
* Sets custom request router. The internal default implementation works well.
* No need to set unless you have special requirements.
*
* <p>Default: Internal default implementation
*
* @param router the request router
* @param router the custom request router implementation
* @return this builder
*/
public Builder router(Router<Void, Endpoint> router) {
Expand Down