MultiShardStatement Class

Package:

com.microsoft.azure.elasticdb.query.multishard

• 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