MultiShardStatement Class

  • java.lang.Object
    • AutoCloseable
      • com.microsoft.azure.elasticdb.query.multishard.MultiShardStatement

public class MultiShardStatement

Complements the MultiShardConnection with a command object similar to the triad of Connection, Statement, and ResultSet. The MultiShardStatement takes a T-SQL command statement as its input and executes the command across its collection of shards specified by its corresponding MultiShardConnection. The results from processing the MultiShardStatement are made available through the execute methods and the MultiShardResultSet. Purpose: Complements the MultiShardConnection and abstracts away the work of running a given command against multiple shards Notes: This class is NOT thread-safe. Since the Sync API internally invokes the async API, connections to shards with connection string property "context connection = true" are not supported. Transaction semantics are not supported.

Field Summary

Modifier and Type Field and Description

Event<EventHandler<ShardExecutionEventArgs>>

shardExecutionBegan

The event handler invoked when execution has begun on a given shard.

Event<EventHandler<ShardExecutionEventArgs>>

shardExecutionCanceled

The event handler invoked when execution on a given shard is canceled, either explicitly via the provided CancellationToken or implicitly as a result of the chosen MultiShardExecutionPolicy.

Event<EventHandler<ShardExecutionEventArgs>>

shardExecutionFaulted

The event handler invoked when execution on a given shard has faulted. This handler is only invoked on exceptions for which execution could not be retried further as a result of the exception's non-transience or as a result of the chosen RetryBehavior.

Event<EventHandler<ShardExecutionEventArgs>>

shardExecutionReaderReturned

The event handler invoked when executeQuery on a certain shard has successfully returned a reader. This is an internal-only method, and differs from shardExecutionSucceeded in that it is invoked BEFORE the reader is added to the MultiShardResultSet; this adding is rife with side effects that are difficult to isolate.

Event<EventHandler<ShardExecutionEventArgs>>

shardExecutionSucceeded

The event handler invoked when execution has successfully completed on a given shard or its shard-specific ResultSet has been returned.

Method Summary

Modifier and Type Method and Description
void cancel()

Attempts to cancel an in progress MultiShardStatement and any ongoing work that is performed at the shards on behalf of the command. We don't want cancel throwing any exceptions. Just cancel.

void close()
MultiShardStatement create(MultiShardConnection connection, String commandText)

Instance constructor of this class. Default command timeout of 300 seconds is used.

MultiShardStatement create(MultiShardConnection connection, String commandText, int commandTimeout)

Instance constructor of this class. Default command type is text.

void dispose(boolean disposing)

Dispose off any unmanaged/managed resources held. We purposely want to ignore exceptions.

MultiShardResultSet executeQuery()

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

MultiShardResultSet executeQuery(CommandBehavior behavior)

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

MultiShardResultSet executeQuery(CommandBehavior behavior, RetryPolicy commandRetryPolicy, MultiShardExecutionPolicy executionPolicy)

Runs the given query against all shards and returns a reader that encompasses results from them. Design Principles - Commands are executed in a parallel, non-blocking manner. - Only the calling thread is blocked until the command is complete against all shards.

Callable<MultiShardResultSet>

executeQueryAsync()

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

Callable<MultiShardResultSet>

executeQueryAsync(CommandBehavior behavior)

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

Callable<MultiShardResultSet>

executeQueryAsync(CommandBehavior behavior, RetryPolicy commandRetryPolicy, MultiShardExecutionPolicy executionPolicy)

Executes the given query against all shards asynchronously.

String getCommandText()

Gets the command text to execute against the set of shards.

int getCommandTimeout()

Time in seconds to wait for the command to be executed on ALL shards. A value of 0 indicates no wait time limit. The default is 300 seconds.

int getCommandTimeoutPerShard()

This property controls the timeout for running a command against individual shards.

MultiShardConnection getConnection()
MultiShardExecutionOptions getExecutionOptions()
MultiShardExecutionPolicy getExecutionPolicy()
RetryBehavior getRetryBehavior()
RetryPolicy getRetryPolicy()
void resetCommandTimeout()

Resets the commandTimeout property to its default value.

void resetCommandTimeoutPerShard()

Resets the CommandTimeoutPerShard property to its default value.

void setCommandText(String value)

Sets the command text to execute against the set of shards.

void setCommandTimeout(int commandTimeout)
void setCommandTimeoutPerShard(int value)

This property controls the timeout for running a command against individual shards.

void setExecutionOptions(MultiShardExecutionOptions value)
void setExecutionPolicy(MultiShardExecutionPolicy value)
void setParameters(int index, int type, Object... objects)

Set query parameters. Currently only Table type parameter is supported.

void setRetryBehavior(RetryBehavior value)
void setRetryPolicy(RetryPolicy value)

Field Details

shardExecutionBegan

public Event<>> shardExecutionBegan= new Event<>()

The event handler invoked when execution has begun on a given shard.

shardExecutionCanceled

public Event<>> shardExecutionCanceled= new Event<>()

The event handler invoked when execution on a given shard is canceled, either explicitly via the provided CancellationToken or implicitly as a result of the chosen MultiShardExecutionPolicy.

shardExecutionFaulted

public Event<>> shardExecutionFaulted= new Event<>()

The event handler invoked when execution on a given shard has faulted. This handler is only invoked on exceptions for which execution could not be retried further as a result of the exception's non-transience or as a result of the chosen RetryBehavior.

shardExecutionReaderReturned

public Event<>> shardExecutionReaderReturned= new Event<>()

The event handler invoked when executeQuery on a certain shard has successfully returned a reader. This is an internal-only method, and differs from shardExecutionSucceeded in that it is invoked BEFORE the reader is added to the MultiShardResultSet; this adding is rife with side effects that are difficult to isolate.

shardExecutionSucceeded

public Event<>> shardExecutionSucceeded= new Event<>()

The event handler invoked when execution has successfully completed on a given shard or its shard-specific ResultSet has been returned.

Method Details

cancel

public void cancel()

Attempts to cancel an in progress MultiShardStatement and any ongoing work that is performed at the shards on behalf of the command. We don't want cancel throwing any exceptions. Just cancel.

close

public void close()

create

public static MultiShardStatement create(MultiShardConnection connection, String commandText)

Instance constructor of this class. Default command timeout of 300 seconds is used.

Parameters:

connection - The connection to shards
commandText - The command text to execute against shards

Returns:

An Instance of this class.

create

public static MultiShardStatement create(MultiShardConnection connection, String commandText, int commandTimeout)

Instance constructor of this class. Default command type is text.

Parameters:

connection - The connection to shards
commandText - The command text to execute against shards
commandTimeout - Command timeout for given commandText to be run against ALL shards

Returns:

An Instance of this class.

dispose

protected void dispose(boolean disposing)

Dispose off any unmanaged/managed resources held. We purposely want to ignore exceptions.

Parameters:

disposing

executeQuery

public MultiShardResultSet executeQuery()

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

Returns:

the MultiShardResultSet instance with the overall concatenated result set.

Throws:

IllegalStateException - thrown if the commandText is null or empty
TimeoutException - thrown if the CommandTimeout elapsed prior to completion

executeQuery

public MultiShardResultSet executeQuery(CommandBehavior behavior)

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

Parameters:

behavior - specifies the CommandBehavior to use.

Returns:

the MultiShardResultSet instance with the overall concatenated ResultSet.

Throws:

IllegalStateException - thrown if the commandText is null or empty
TimeoutException - thrown if the CommandTimeout elapsed prior to completion

executeQuery

public MultiShardResultSet executeQuery(CommandBehavior behavior, RetryPolicy commandRetryPolicy, MultiShardExecutionPolicy executionPolicy)

Runs the given query against all shards and returns a reader that encompasses results from them. Design Principles - Commands are executed in a parallel, non-blocking manner. - Only the calling thread is blocked until the command is complete against all shards.

Parameters:

behavior - Command behavior to use
commandRetryPolicy - The retry policy to use when executing commands against the shards
executionPolicy - The execution policy to use

Returns:

MultiShardResultSet instance that encompasses results from all shards

Throws:

IllegalStateException - If the commandText is null or empty
TimeoutException - If the commandTimeout elapsed prior to completion
MultiShardAggregateException - If one or more errors occurred while executing the query

executeQueryAsync

public Callable executeQueryAsync()

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

Returns:

a task wrapping the MultiShardResultSet instance with the overall concatenated result set.

Throws:

IllegalStateException - thrown if the commandText is null or empty, or if the specified command behavior is not supported such as CloseConnection or SingleRow.
TimeoutException - thrown if the commandTimeout elapsed prior to completion.

executeQueryAsync

public Callable executeQueryAsync(CommandBehavior behavior)

The ExecuteReader methods of the MultiShardStatement execute the given command statement on each shard and return the concatenation (i.e. UNION ALL) of the individual results from the shards in a MultiShardResultSet. The execution policy regarding result completeness can be controlled by setting the MultiShardExecutionPolicy. The default execution policy is to return complete results.

Parameters:

behavior - Command behavior to use

Returns:

a task wrapping the MultiShardResultSet instance with the overall concatenated result set.

Throws:

IllegalStateException - thrown if the commandText is null or empty, or if the specified command behavior is not supported such as CloseConnection or SingleRow.
TimeoutException - thrown if the commandTimeout elapsed prior to completion.

executeQueryAsync

public Callable executeQueryAsync(CommandBehavior behavior, RetryPolicy commandRetryPolicy, MultiShardExecutionPolicy executionPolicy)

Executes the given query against all shards asynchronously.

Parameters:

behavior - Command behavior to use
commandRetryPolicy - The retry policy to use when executing commands against the shards
executionPolicy - The execution policy to use

Returns:

A task with a ResultT that encompasses results from all shards Any exceptions during command execution are conveyed via the returned Task

Throws:

IllegalStateException - If the commandText is null or empty

getCommandText

public String getCommandText()

Gets the command text to execute against the set of shards.

getCommandTimeout

public int getCommandTimeout()

Time in seconds to wait for the command to be executed on ALL shards. A value of 0 indicates no wait time limit. The default is 300 seconds.

getCommandTimeoutPerShard

public int getCommandTimeoutPerShard()

This property controls the timeout for running a command against individual shards.

getConnection

public MultiShardConnection getConnection()

getExecutionOptions

public MultiShardExecutionOptions getExecutionOptions()

getExecutionPolicy

public MultiShardExecutionPolicy getExecutionPolicy()

getRetryBehavior

public RetryBehavior getRetryBehavior()

getRetryPolicy

public RetryPolicy getRetryPolicy()

resetCommandTimeout

public void resetCommandTimeout()

Resets the commandTimeout property to its default value.

resetCommandTimeoutPerShard

public void resetCommandTimeoutPerShard()

Resets the CommandTimeoutPerShard property to its default value.

setCommandText

public void setCommandText(String value)

Sets the command text to execute against the set of shards.

Parameters:

value

setCommandTimeout

public void setCommandTimeout(int commandTimeout)

Parameters:

commandTimeout

setCommandTimeoutPerShard

public void setCommandTimeoutPerShard(int value)

This property controls the timeout for running a command against individual shards.

Parameters:

value

setExecutionOptions

public void setExecutionOptions(MultiShardExecutionOptions value)

Parameters:

value

setExecutionPolicy

public void setExecutionPolicy(MultiShardExecutionPolicy value)

Parameters:

value

setParameters

public void setParameters(int index, int type, Object... objects)

Set query parameters. Currently only Table type parameter is supported.

Parameters:

index - Index of the parameter
type - SQL Type of the parameter
objects - An array of objects to add as parameter

setRetryBehavior

public void setRetryBehavior(RetryBehavior value)

Parameters:

value

setRetryPolicy

public void setRetryPolicy(RetryPolicy value)

Parameters:

value

Applies to