com.microsoft.azure.storage.table

Class CloudTableClient

java.lang.Object

com.microsoft.azure.storage.ServiceClient

com.microsoft.azure.storage.table.CloudTableClient

public final class CloudTableClient
extends ServiceClient

Provides a service client for accessing the Microsoft Azure Table service.

The CloudTableClient class encapsulates the base URI for the Table service endpoint and the credentials for accessing the storage account, and provides methods to create, delete, list, and query tables, as well as methods to execute operations and queries on table entities. These methods invoke Storage Service REST API operations to make the requests and obtain the results that are returned.

A Table service endpoint is the base URI for Table service resources, including the DNS name of the storage account:
http://myaccount.table.core.windows.net
For more information, see the MSDN topic Addressing Table Service Resources.

The credentials can be a combination of the storage account name and a key, or a shared access signature. For more information, see the MSDN topic Authenticating Access to Your Storage Account.

Field Summary

Fields inherited from class com.microsoft.azure.storage.ServiceClient

credentials

Constructor Summary

Constructors

Constructor and Description
CloudTableClient(StorageUri baseUri, StorageCredentials credentials) Initializes an instance of the CloudTableClientclass using a Table service endpoint and storage account credentials.
CloudTableClient(URI baseUri, StorageCredentials credentials) Initializes an instance of the CloudTableClient class using a Table service endpoint and storage account credentials.

Method Summary

Modifier and Type	Method and Description
ServiceProperties	downloadServiceProperties() Retrieves the current ServiceProperties for the given storage service.
ServiceProperties	downloadServiceProperties(TableRequestOptions options, OperationContext opContext) Retrieves the current ServiceProperties for the given storage service.
protected <T extends TableEntity,R> ResultSegment<?>	executeQuerySegmentedImpl(TableQuery<T> queryToExecute, EntityResolver<R> resolver, ResultContinuation continuationToken, TableRequestOptions options, OperationContext opContext) Reserved for internal use.
protected <T extends TableEntity,R> Iterable<?>	generateIteratorForQuery(TableQuery<T> queryRef, EntityResolver<R> resolver, TableRequestOptions options, OperationContext opContext) Reserved for internal use.
TableRequestOptions	getDefaultRequestOptions() Gets the TableRequestOptions that is used for requests associated with this CloudTableClient
ServiceStats	getServiceStats() Queries the service for the ServiceStats.
ServiceStats	getServiceStats(TableRequestOptions options, OperationContext opContext) Queries the given storage service for the ServiceStats.
CloudTable	getTableReference(String tableName) Gets a CloudTable object with the specified name.
protected StorageUri	getTransformedEndPoint(OperationContext opContext)
protected boolean	isUsePathStyleUris() Indicates whether path-style URIs are used.
Iterable<String>	listTables() Lists the table names in the storage account.
Iterable<String>	listTables(String prefix) Lists the table names in the storage account that match the specified prefix.
Iterable<String>	listTables(String prefix, TableRequestOptions options, OperationContext opContext) Lists the table names in the storage account that match the specified prefix, using the specified TableRequestOptions and OperationContext.
ResultSegment<String>	listTablesSegmented() Lists the table names in the storage account in segmented mode.
ResultSegment<String>	listTablesSegmented(String prefix) Lists the table names in the storage account that match the specified prefix in segmented mode.
ResultSegment<String>	listTablesSegmented(String prefix, Integer maxResults, ResultContinuation continuationToken, TableRequestOptions options, OperationContext opContext) Lists up to the specified maximum of the table names in the storage account that match the specified prefix in a resumable mode with the specified ResultContinuation continuation token, using the specified TableRequestOptions and OperationContext.
void	setDefaultRequestOptions(TableRequestOptions defaultRequestOptions) Sets the TableRequestOptions that is used for any table accessed with this CloudTableClient object.
void	uploadServiceProperties(ServiceProperties properties) Uploads a new ServiceProperties configuration to the given storage service.
void	uploadServiceProperties(ServiceProperties properties, TableRequestOptions options, OperationContext opContext) Uploads a new ServiceProperties configuration to the given storage service.

Methods inherited from class com.microsoft.azure.storage.ServiceClient

downloadServicePropertiesImpl, getCredentials, getEndpoint, getServiceStatsImpl, getStorageUri, setCredentials, setStorageUri, uploadServicePropertiesImpl

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CloudTableClient

public CloudTableClient(URI baseUri,
                        StorageCredentials credentials)

Initializes an instance of the CloudTableClient class using a Table service endpoint and storage account credentials.

Parameters:

baseUri - A java.net.URI object that represents the Table service endpoint used to initialize the client.

credentials - A StorageCredentials object that represents the storage account credentials for access.

CloudTableClient

public CloudTableClient(StorageUri baseUri,
                        StorageCredentials credentials)

Initializes an instance of the CloudTableClientclass using a Table service endpoint and storage account credentials.

Parameters:

baseUri - A StorageUri object that represents the Table service endpoint used to initialize the client.

credentials - A StorageCredentials object that represents the storage account credentials for access.

Method Detail

getTableReference

public CloudTable getTableReference(String tableName)
                             throws URISyntaxException,
                                    StorageException

Gets a CloudTable object with the specified name.

Parameters:

tableName - A String which represents the name of the table, which must adhere to table naming rules. The table name should not include any path separator characters (/). Table names are case insensitive, must be unique within an account and must be between 3-63 characters long. Table names must start with an cannot begin with a numeric character and may only contain alphanumeric characters. Some table names are reserved, including "table".

Returns:

A reference to a CloudTable object.

Throws:

URISyntaxException - If the resource URI constructed based on the tableName is invalid.

StorageException - If a storage service error occurred.

See Also:

Understanding the Table Service Data Model

listTables

@DoesServiceRequest
public Iterable<String> listTables()

Lists the table names in the storage account.

This method invokes the Query Tables REST API to list the table names, using the Table service endpoint and storage account credentials of this instance.

Returns:

An Iterable collection of the table names in the storage account retrieved lazily.

listTables

@DoesServiceRequest
public Iterable<String> listTables(String prefix)

Lists the table names in the storage account that match the specified prefix.

This method invokes the Query Tables REST API to list the table names that match the prefix, using the Table service endpoint and storage account credentials of this instance.

Parameters:

prefix - A String containing the prefix to match on table names to return.

Returns:

An Iterable collection of the table names in the storage account retrieved lazily that match the specified prefix.

listTables

@DoesServiceRequest
public Iterable<String> listTables(String prefix,
                                                       TableRequestOptions options,
                                                       OperationContext opContext)

Lists the table names in the storage account that match the specified prefix, using the specified TableRequestOptions and OperationContext.

This method invokes the Query Tables REST API to list the table names that match the prefix, using the Table service endpoint and storage account credentials of this instance. Use the TableRequestOptions to override execution options such as the timeout or retry policy for the operation.

Parameters:

prefix - A String containing the prefix to match on table names to return.

options - A TableRequestOptions object that specifies execution options such as retry policy and timeout settings for the operation. Specify null to use the request options specified on the CloudTableClient.

opContext - An OperationContext object for tracking the current operation. Specify null to safely ignore operation context.

Returns:

An Iterable collection of the table names in the storage account retrieved lazily that match the specified prefix.

listTablesSegmented

@DoesServiceRequest
public ResultSegment<String> listTablesSegmented()
                                                              throws StorageException

Lists the table names in the storage account in segmented mode. This method allows listing of tables to be resumed after returning a partial set of results, using information returned by the server in the ResultSegment object.

This method invokes the Query Tables REST API to list the table names, using the Table service endpoint and storage account credentials of this instance.

Returns:

A ResultSegment of String objects containing table names in the storage account.

Throws:

StorageException - if a storage service error occurred during the operation.

listTablesSegmented

@DoesServiceRequest
public ResultSegment<String> listTablesSegmented(String prefix)
                                                              throws StorageException

Lists the table names in the storage account that match the specified prefix in segmented mode. This method allows listing of tables to be resumed after returning a partial set of results, using information returned by the server in the ResultSegment object.

This method invokes the Query Tables REST API to list the table names that match the prefix, using the Table service endpoint and storage account credentials of this instance.

Parameters:

prefix - A String containing the prefix to match on table names to return.

Returns:

A ResultSegment of String objects containing table names matching the prefix in the storage account.

Throws:

StorageException - if a storage service error occurred during the operation.

listTablesSegmented

@DoesServiceRequest
public ResultSegment<String> listTablesSegmented(String prefix,
                                                                     Integer maxResults,
                                                                     ResultContinuation continuationToken,
                                                                     TableRequestOptions options,
                                                                     OperationContext opContext)
                                                              throws StorageException

Lists up to the specified maximum of the table names in the storage account that match the specified prefix in a resumable mode with the specified ResultContinuation continuation token, using the specified TableRequestOptions and OperationContext. This method allows listing of tables to be resumed after returning a page of results, using information returned by the server in the ResultSegment object.

This method invokes the Query Tables REST API to list the table names that match the prefix, using the Table service endpoint and storage account credentials of this instance. Use the TableRequestOptions to override execution options such as the timeout or retry policy for the operation.

Parameters:

prefix - A String containing the prefix to match on table names to return.

maxResults - The maximum number of table names to return in the ResultSegment. If this parameter is null, the query will list up to the maximum 1,000 results.

continuationToken - A ResultContinuation object representing a continuation token from the server when the operation returns a partial result. Specify null on the initial call. Call the ResultSegment.getContinuationToken() method on the result to obtain the ResultContinuation object to use in the next call to resume the query.

options - A TableRequestOptions object that specifies execution options such as retry policy and timeout settings for the operation. Specify null to use the request options specified on the CloudTableClient.

opContext - An OperationContext object for tracking the current operation. Specify null to safely ignore operation context.

Returns:

A ResultSegment of String objects containing table names in the storage account.

Throws:

StorageException - if a storage service error occurred during the operation.

executeQuerySegmentedImpl

protected <T extends TableEntity,R> ResultSegment<?> executeQuerySegmentedImpl(TableQuery<T> queryToExecute,
                                                                               EntityResolver<R> resolver,
                                                                               ResultContinuation continuationToken,
                                                                               TableRequestOptions options,
                                                                               OperationContext opContext)
                                                                        throws StorageException

Reserved for internal use. Executes a segmented query operation using the specified retry and timeout policies.

Parameters:

queryToExecute - The TableQuery to execute.

resolver - An EntityResolver instance which creates a projection of the table query result entities into the specified type R. Pass null to return the results as the table entity type.

continuationToken - The ResultContinuation to pass with the operation to resume a query, if any. Pass null for an initial query.

options - A TableRequestOptions object that specifies execution options such as retry policy and timeout settings for the operation. Specify null to use the request options specified on the CloudTableClient.

opContext - An OperationContext object for tracking the current operation. Specify null to safely ignore operation context.

Returns:

A ResultSegment containing a collection of the query results specialized for the TableEntity or EntityResolver type returned by the query.

Throws:

StorageException - if a Storage service error occurs.

getTransformedEndPoint

protected final StorageUri getTransformedEndPoint(OperationContext opContext)
                                           throws URISyntaxException,
                                                  StorageException

Throws:

URISyntaxException

StorageException

generateIteratorForQuery

protected <T extends TableEntity,R> Iterable<?> generateIteratorForQuery(TableQuery<T> queryRef,
                                                                         EntityResolver<R> resolver,
                                                                         TableRequestOptions options,
                                                                         OperationContext opContext)

Reserved for internal use. Generates an iterator for a segmented query operation.

Parameters:

queryRef - The TableQuery to execute.

resolver - An EntityResolver instance which creates a projection of the table query result entities into the specified type R. Pass null to return the results as the table entity type.

options - A TableRequestOptions object that specifies execution options such as retry policy and timeout settings for the operation. Specify null to use the request options specified on the CloudTableClient.

opContext - An OperationContext object for tracking the current operation. Specify null to safely ignore operation context.

Returns:

An instance of Iterable specialized for the TableEntity or EntityResolver type returned by the query.

getServiceStats

@DoesServiceRequest
public ServiceStats getServiceStats()
                                                 throws StorageException

Queries the service for the ServiceStats.

Returns:

ServiceStats for the given storage service

Throws:

StorageException - If a storage service error occurred.

getServiceStats

@DoesServiceRequest
public ServiceStats getServiceStats(TableRequestOptions options,
                                                        OperationContext opContext)
                                                 throws StorageException

Queries the given storage service for the ServiceStats.

Parameters:

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

ServiceStats for the given storage service

Throws:

StorageException - If a storage service error occurred.

downloadServiceProperties

@DoesServiceRequest
public final ServiceProperties downloadServiceProperties()
                                                                      throws StorageException

Retrieves the current ServiceProperties for the given storage service. This includes Logging, HourMetrics, MinuteMetrics and CORS configurations.

Returns:

the ServiceProperties object representing the current configuration of the service.

Throws:

StorageException - If a storage service error occurred.

downloadServiceProperties

@DoesServiceRequest
public final ServiceProperties downloadServiceProperties(TableRequestOptions options,
                                                                             OperationContext opContext)
                                                                      throws StorageException

Retrieves the current ServiceProperties for the given storage service. This includes Logging, HourMetrics, MinuteMetrics and CORS configurations.

Parameters:

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

the ServiceProperties object representing the current configuration of the service.

Throws:

StorageException - If a storage service error occurred.

uploadServiceProperties

@DoesServiceRequest
public void uploadServiceProperties(ServiceProperties properties)
                                                 throws StorageException

Uploads a new ServiceProperties configuration to the given storage service. This includes Logging, HourMetrics, MinuteMetrics and CORS configurations.

Parameters:

properties - The ServiceProperties to upload.

Throws:

StorageException - If a storage service error occurred.

uploadServiceProperties

@DoesServiceRequest
public void uploadServiceProperties(ServiceProperties properties,
                                                        TableRequestOptions options,
                                                        OperationContext opContext)
                                                 throws StorageException

Uploads a new ServiceProperties configuration to the given storage service. This includes Logging, HourMetrics, MinuteMetrics and CORS configurations.

Parameters:

properties - The ServiceProperties to upload.

options - A BlobRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudBlobClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

getDefaultRequestOptions

public TableRequestOptions getDefaultRequestOptions()

Gets the TableRequestOptions that is used for requests associated with this CloudTableClient

Specified by:

getDefaultRequestOptions in class ServiceClient

Returns:

The TableRequestOptions object containing the values used by this CloudTableClient

setDefaultRequestOptions

public void setDefaultRequestOptions(TableRequestOptions defaultRequestOptions)

Sets the TableRequestOptions that is used for any table accessed with this CloudTableClient object.

Parameters:

defaultRequestOptions - The TableRequestOptions to use.

isUsePathStyleUris

protected boolean isUsePathStyleUris()

Indicates whether path-style URIs are used.

Overrides:

isUsePathStyleUris in class ServiceClient

Returns:

true if path-style URIs are used; otherwise false.