ExclusiveDBConnectionPool

The Java API provides ExclusiveDBConnectionPool for executing tasks. Each worker exclusively owns one DBConnection. Users can submit tasks with execute and obtain task results through getResult of BasicDBTask.

Starting from Java API 3.00.5.2, ExclusiveDBConnectionPool adds minimumPoolSize, maximumPoolSize, and idleTimeout. These parameters allow the pool to expand dynamically based on task pressure and shrink back to the minimum size after workers become idle. For compatibility, existing constructors and existing public method signatures remain unchanged.

Usage

ExclusiveDBConnectionPool supports two usage modes:

Fixed-size mode: use existing constructors and specify the number of connections with count.
Elastic pool mode: available since Java API 3.00.5.2. Use the new constructors or ExclusiveDBConnectionPoolConfig and control pool capacity with minimumPoolSize, maximumPoolSize, and idleTimeout.

Fixed-Size Mode

Existing constructors remain unchanged:

public ExclusiveDBConnectionPool(
    String host,
    int port,
    String uid,
    String pwd,
    int count,
    boolean loadBalance,
    boolean enableHighAvailability
) throws IOException

public ExclusiveDBConnectionPool(
    String host,
    int port,
    String uid,
    String pwd,
    int count,
    boolean loadBalance,
    boolean enableHighAvailability,
    String[] highAvailabilitySites,
    String initialScript,
    boolean compress,
    boolean useSSL,
    boolean usePython
) throws IOException

Parameters

host: Host name.

port: Port number.

uid: Optional. User name. The default value is "".

pwd: Optional. Password. The default value is "".

count: A positive integer indicating the number of connections in fixed-size mode. If the number of submitted tasks exceeds the number of connections, some tasks wait until a connection becomes available.

loadBalance: Whether to enable load balancing when initializing connections.

enableHighAvailability: Optional. Whether to enable high availability for connections in the pool. The default value is false.

highAvailabilitySites: Optional. A String array of available node addresses and ports in ip:port format. This parameter is used only when enableHighAvailability is enabled. The default value is null.

initialScript: Optional. Initialization script. The default value is "".

compress: Optional. Whether to compress data during download. The default value is false.

useSSL: Optional. Whether to use SSL. The default value is false. To enable SSL, the server configuration file must also set enableHTTPS=true.

usePython: Optional. Whether to enable Python parsing. The default value is false.

Compatibility note:

Starting from Java API 3.00.5.2, count in existing constructors is internally mapped to minimumPoolSize and maximumPoolSize = count. Therefore, fixed-size behavior is preserved. Existing constructors do not trigger dynamic expansion or idleTimeout recycling.

Elastic Pool Mode

Starting from Java API 3.00.5.2, the following constructors are added:

public ExclusiveDBConnectionPool(
    String host,
    int port,
    String uid,
    String pwd,
    int minimumPoolSize,
    int maximumPoolSize,
    int idleTimeout,
    boolean loadBalance,
    boolean enableHighAvailability
) throws IOException

public ExclusiveDBConnectionPool(
    String host,
    int port,
    String uid,
    String pwd,
    int minimumPoolSize,
    int maximumPoolSize,
    int idleTimeout,
    boolean loadBalance,
    boolean enableHighAvailability,
    String[] highAvailabilitySites,
    String initialScript,
    boolean compress,
    boolean useSSL,
    boolean usePython
) throws IOException

New Parameters

minimumPoolSize: A positive integer indicating the minimum number of workers/connections created during pool initialization. Idle recycling never reduces the current connection count below this value. The default value is 5. If the value is less than or equal to 0, the default value 5 is used.

maximumPoolSize: A positive integer indicating the maximum number of workers/connections to which the pool can expand. The default value is 5. If the value is less than or equal to 0, the default value 5 is used. If it is smaller than minimumPoolSize, it is adjusted to minimumPoolSize.

idleTimeout: An int value indicating the maximum idle time, in milliseconds, for workers beyond minimumPoolSize. After this time, the worker exits and closes its exclusive DBConnection. The default value is 600000, or 10 minutes. The minimum valid value is 10000, or 10 seconds. If the configured value is less than 10000, the default value 600000 is used.

Using ExclusiveDBConnectionPoolConfig

Starting from Java API 3.00.5.2, ExclusiveDBConnectionPoolConfig is added to hold connection parameters and elastic pool parameters.

public ExclusiveDBConnectionPool(ExclusiveDBConnectionPoolConfig config) throws IOException

ExclusiveDBConnectionPoolConfig can only be configured through setXxx methods. Example:

ExclusiveDBConnectionPoolConfig config = new ExclusiveDBConnectionPoolConfig();
config.setHostName(HOST);
config.setPort(PORT);
config.setUserId(USER);
config.setPassword(PASSWORD);
config.setMinimumPoolSize(1);
config.setMaximumPoolSize(3);
config.setIdleTimeout(10000);
config.setLoadBalance(false);
config.setEnableHighAvailability(false);

ExclusiveDBConnectionPool pool = new ExclusiveDBConnectionPool(config);

ExclusiveDBConnectionPoolConfig supports the following parameters:

hostName: Host name. The default value is "localhost".

port: Port number. The default value is 8848.

userId: User name. The default value is "".

password: Password. The default value is "".

minimumPoolSize: Minimum number of workers/connections in the pool. The default value is 5.

maximumPoolSize: Maximum number of workers/connections allowed in the pool at the same time. The default value is 5.

idleTimeout: Maximum idle time, in milliseconds, for workers beyond minimumPoolSize. The default value is 600000.

initialScript: Initialization script. The default value is "".

compress: Whether to compress data during download. The default value is false.

useSSL: Whether to use SSL. The default value is false.

usePython: Whether to enable Python parsing. The default value is false.

loadBalance: Whether to enable load balancing. The default value is false.

enableHighAvailability: Whether to enable high availability. The default value is false.

highAvailabilitySites: A String array of host names and port numbers specified when high availability is enabled. The default value is null.

Mapping Between Existing and New Parameters

Starting from Java API 3.00.5.2, count maps to the new parameters as follows:


Entry	minimumPoolSize	maximumPoolSize	idleTimeout	Final Behavior
Existing constructors with count	count	count	Not effective	Keeps exactly count connections. No dynamic expansion or shrinking is performed.
New constructors	User-configured minimumPoolSize	User-configured and validated maximumPoolSize	Effective for idle workers beyond minimumPoolSize	Initializes the pool with the minimum number of connections, expands up to the maximum under task pressure, and shrinks back to the minimum after workers are idle.
ExclusiveDBConnectionPoolConfig	User-configured value or default value	User-configured value or default value, guaranteed to be no smaller than minimumPoolSize	User-configured value or default value	Initializes the pool with the minimum number of connections, expands up to the maximum under task pressure, and shrinks back to the minimum after workers are idle.

Note:

The meaning of count in existing constructors remains unchanged. It still indicates a fixed number of connections and is not automatically converted into elastic pool behavior by the addition of minimumPoolSize, maximumPoolSize, and idleTimeout.

Examples

The following examples assume that HOST, PORT, USER, PASSWORD, and HA_SITES are defined through environment variables or configuration files.

The following example creates a fixed-size connection pool with 5 connections. Load balancing and high availability are enabled, high-availability sites are specified, compression and SSL are enabled, and Python parsing is disabled.

public void demoExclusiveDBConnectionPool() throws IOException {
    DBConnectionPool pool = new ExclusiveDBConnectionPool(
        HOST,
        PORT,
        USER,
        PASSWORD,
        5,
        true,
        true,
        HA_SITES,
        "",
        true,
        true,
        false
    );
}

Starting from Java API 3.00.5.2, this usage still keeps fixed-size behavior. The pool initializes 5 connections and does not dynamically expand or recycle idle workers.

The following example creates an elastic connection pool. It initializes 1 connection and can expand to at most 3 connections when task pressure increases. Workers beyond the minimum size automatically exit and close their exclusive connections after being idle for 10 seconds.

public void demoDynamicExclusiveDBConnectionPool() throws IOException {
    ExclusiveDBConnectionPool pool = new ExclusiveDBConnectionPool(
        HOST,
        PORT,
        USER,
        PASSWORD,
        1,
        3,
        10000,
        false,
        false
    );

    List<DBTask> tasks = new ArrayList<>();
    tasks.add(new BasicDBTask("sleep(1000); 1"));
    tasks.add(new BasicDBTask("sleep(1000); 1"));
    tasks.add(new BasicDBTask("sleep(1000); 1"));

    pool.execute(tasks);
    pool.shutdown();
}

public void demoExclusiveDBConnectionPoolConfig() throws IOException {
    ExclusiveDBConnectionPoolConfig config = new ExclusiveDBConnectionPoolConfig();
    config.setHostName(HOST);
    config.setPort(PORT);
    config.setUserId(USER);
    config.setPassword(PASSWORD);
    config.setMinimumPoolSize(1);
    config.setMaximumPoolSize(3);
    config.setIdleTimeout(10000);
    config.setLoadBalance(false);
    config.setEnableHighAvailability(false);

    ExclusiveDBConnectionPool pool = new ExclusiveDBConnectionPool(config);
    DBTask task = new BasicDBTask("1 + 1");
    pool.execute(task);

    System.out.println(task.getResult());
    pool.shutdown();
}

Methods

The following methods are provided by ExclusiveDBConnectionPool:

Note:

getCurrentConnectionCount(), getMinimumPoolSize(), getMaximumPoolSize(), getIdleTimeout(), getActiveConnectionsCount(), and getIdleConnectionsCount() are newly added methods on the concrete ExclusiveDBConnectionPool class and are not added to the DBConnectionPool interface. To call these methods, declare the pool variable as ExclusiveDBConnectionPool.


Method	Description
ExclusiveDBConnectionPool(String host, int port, String uid, String pwd, int count, boolean loadBalance, boolean enableHighAvailability)	Constructor that creates a connection pool in fixed-size mode.
ExclusiveDBConnectionPool(String host, int port, String uid, String pwd, int count, boolean loadBalance, boolean enableHighAvailability, String[] highAvailabilitySites, String initialScript, boolean compress, boolean useSSL, boolean usePython)	Constructor that creates a connection pool in fixed-size mode and supports high-availability sites, initialization script, compression, SSL, and Python parsing.
ExclusiveDBConnectionPool(String host, int port, String uid, String pwd, int minimumPoolSize, int maximumPoolSize, int idleTimeout, boolean loadBalance, boolean enableHighAvailability)	Added in Java API 3.00.5.2. Constructor that creates an elastic connection pool.
ExclusiveDBConnectionPool(String host, int port, String uid, String pwd, int minimumPoolSize, int maximumPoolSize, int idleTimeout, boolean loadBalance, boolean enableHighAvailability, String[] highAvailabilitySites, String initialScript, boolean compress, boolean useSSL, boolean usePython)	Added in Java API 3.00.5.2. Constructor that creates an elastic connection pool and supports high-availability sites, initialization script, compression, SSL, and Python parsing.
ExclusiveDBConnectionPool(ExclusiveDBConnectionPoolConfig config)	Added in Java API 3.00.5.2. Creates an elastic connection pool from the configuration class.
execute(DBTask task)	Executes a single task.
execute(DBTask task, int timeOut)	Executes a single task and sets the wait timeout in milliseconds.
execute(List<DBTask> tasks)	Executes multiple tasks.
waitForThreadCompletion()	Waits until all submitted tasks are complete.
getConnectionCount()	Gets the current number of live workers/connections. In fixed-size mode, it is equal to count. In elastic pool mode, it may change between minimumPoolSize and maximumPoolSize.
getCurrentConnectionCount()	Added in Java API 3.00.5.2. Gets the current number of live workers/connections. In fixed-size mode, it is equal to count. In elastic pool mode, it may change between minimumPoolSize and maximumPoolSize.
getMinimumPoolSize()	Added in Java API 3.00.5.2. Gets the minimum number of workers/connections.
getMaximumPoolSize()	Added in Java API 3.00.5.2. Gets the maximum number of workers/connections, that is, the maximum capacity to which the elastic pool can expand.
getIdleTimeout()	Added in Java API 3.00.5.2. Gets the idle recycling timeout in milliseconds.
getActiveConnectionsCount()	Added in Java API 3.00.5.2. Gets the number of workers/connections that are currently executing tasks. Queued tasks waiting for execution are not counted.
getIdleConnectionsCount()	Added in Java API 3.00.5.2. Gets the number of workers/connections that have been created but are not executing tasks.
shutdown()	Shuts down the connection pool. This method waits for submitted tasks to complete before releasing connections. Call it explicitly when the pool is no longer needed.

Compatibility note:

getConnectionCount() is an existing method. Starting from Java API 3.00.5.2, its return value still indicates the current number of live workers/connections. For pools created with existing constructors in fixed-size mode, it always equals count. For elastic pools, it changes as the pool expands and recycles idle workers. To obtain the configured maximum concurrency capacity, use getMaximumPoolSize().

When the pool is not closed, the following relationship holds:

getActiveConnectionsCount() + getIdleConnectionsCount() = getCurrentConnectionCount()

Here, idle means that the connection is not currently executing a task. It does not mean that the connection will necessarily be recycled. Only workers/connections beyond minimumPoolSize whose idle time reaches idleTimeout are recycled.

Managing Tasks

Creating a Task

The Java API provides BasicDBTask for creating tasks. BasicDBTask wraps the script, parameters, execution status, and result.

Constructor:

public BasicDBTask(String script)

Parameters

script: A String value indicating the script to execute.

Example:

public void demoBasicDBTask() {
    BasicDBTask task = new BasicDBTask("x=1; x;");
}

Submitting a Task with execute

After creating a task, use execute to submit it to the connection pool.

Parameters

task: A DBTask object indicating a single task.

tasks: A List<DBTask> object indicating multiple tasks.

timeOut: An int value indicating the timeout for waiting for task completion, in milliseconds. The default value is -1, meaning to wait indefinitely.

The following code executes a simple script task with a timeout of 10000:

public void demoExclusiveDBConnectionPool() throws IOException {
    ExclusiveDBConnectionPool pool = new ExclusiveDBConnectionPool(
        HOST,
        PORT,
        USER,
        PASSWORD,
        5,
        false,
        false
    );

    DBTask task = new BasicDBTask("x=1; x;");
    pool.execute(task, 10000);
    pool.shutdown();
}

Submitting Multiple Tasks

To submit multiple tasks at once, declare a List with generic type DBTask.

public void demoExclusiveDBConnectionPool() throws IOException {
    DBConnectionPool pool = new ExclusiveDBConnectionPool(
        HOST,
        PORT,
        USER,
        PASSWORD,
        5,
        false,
        false
    );

    List<DBTask> dbTaskList = new ArrayList<>();
    dbTaskList.add(new BasicDBTask("1 + 1"));
    dbTaskList.add(new BasicDBTask("x = 1; x;"));
    dbTaskList.add(new BasicDBTask("sum(1 2 3 NULL 4);"));

    pool.execute(dbTaskList);
    pool.shutdown();
}

Obtaining Task Return Values

Use the following methods of BasicDBTask to obtain task return values and information:


Method	Description
boolean isSuccessful()	Returns whether the task was executed successfully.
Entity getResult()	Gets the task execution result.
String getErrorMsg()	Gets the exception message generated during task execution.

Example:

public void demoExclusiveDBConnectionPool() throws IOException {
    DBConnectionPool pool = new ExclusiveDBConnectionPool(
        HOST,
        PORT,
        USER,
        PASSWORD,
        5,
        false,
        false
    );

    DBTask task = new BasicDBTask("sum(1 2 3 NULL 4);");
    pool.execute(task);

    System.out.println(task.isSuccessful());
    System.out.println(task.getResult());
    System.out.println(task.getErrorMsg());

    pool.shutdown();
}

Execution result:

true
10
null

Mechanism

When a pool is created with existing constructors, it creates count workers/connections during initialization. Each worker exclusively owns one DBConnection and consumes tasks from the task queue.

count must be a positive integer.
The number of connections is fixed at count after initialization.
No dynamic expansion is performed.
No idleTimeout recycling is performed.
getConnectionCount() returns count.

When a pool is created with the new constructors or ExclusiveDBConnectionPoolConfig, it enters elastic pool mode.

The pool creates minimumPoolSize workers/connections during initialization.
When tasks are submitted, the pool estimates the number of workers required based on the task queue length and the number of tasks currently being executed.
If the current number of workers is smaller than the task demand and has not reached maximumPoolSize, the pool creates new workers.
New workers participate in task consumption immediately after creation.
Workers beyond minimumPoolSize automatically exit after being idle for longer than idleTimeout and close their exclusive DBConnection.

Each worker in ExclusiveDBConnectionPool exclusively owns one DBConnection. In elastic pool mode, idle recycling applies to workers beyond minimumPoolSize and their exclusive connections.

When the current number of workers is greater than minimumPoolSize, idle workers beyond minimumPoolSize can be recycled.
When the current number of workers is less than or equal to minimumPoolSize, workers are not recycled even if their idle time exceeds idleTimeout.
Fixed-size mode does not perform idleTimeout recycling.

When loadBalance = false, all workers in the pool connect to the specified host:port.

When loadBalance = true:

The list of available data nodes is obtained during initialization.
Workers connect to different nodes in round-robin order so that connections are distributed relatively evenly.
In elastic pool mode, workers created during later dynamic expansion reuse the node list obtained during initialization. The pool does not access the controller again each time it expands.

The handling logic for enableHighAvailability and highAvailabilitySites remains the same as in existing constructors.

Use waitForThreadCompletion() to wait until all submitted tasks are complete.

Use shutdown() to close the pool:

pool.shutdown();

shutdown() first waits for submitted tasks to complete, then interrupts workers and releases connections. In elastic pool mode, waitForThreadCompletion() waits for submitted tasks to complete but does not wait for workers to be recycled back to minimumPoolSize. Therefore, it is not blocked by idle workers waiting for idleTimeout.