com.amazonaws.services.dynamodb
Class AmazonDynamoDBClient

java.lang.Object
  extended by com.amazonaws.AmazonWebServiceClient
      extended by com.amazonaws.services.dynamodb.AmazonDynamoDBClient
All Implemented Interfaces:
AmazonDynamoDB
Direct Known Subclasses:
AmazonDynamoDBAsyncClient

public class AmazonDynamoDBClient
extends AmazonWebServiceClient
implements AmazonDynamoDB

Client for accessing AmazonDynamoDB. All service calls made using this client are blocking, and will not return until the service call completes.

Amazon DynamoDB is a fast, highly scalable, highly available, cost-effective non-relational database service.

Amazon DynamoDB removes traditional scalability limitations on data storage while maintaining low latency and predictable performance.


Constructor Summary
AmazonDynamoDBClient()
          Constructs a new client to invoke service methods on AmazonDynamoDB.
AmazonDynamoDBClient(AWSCredentials awsCredentials)
          Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials.
AmazonDynamoDBClient(AWSCredentials awsCredentials, ClientConfiguration clientConfiguration)
          Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials and client configuration options.
AmazonDynamoDBClient(AWSCredentialsProvider awsCredentialsProvider)
          Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials provider.
AmazonDynamoDBClient(AWSCredentialsProvider awsCredentialsProvider, ClientConfiguration clientConfiguration)
          Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials provider and client configuration options.
AmazonDynamoDBClient(ClientConfiguration clientConfiguration)
          Constructs a new client to invoke service methods on AmazonDynamoDB.
 
Method Summary
 BatchGetItemResult batchGetItem(BatchGetItemRequest batchGetItemRequest)
           Retrieves the attributes for multiple items from multiple tables using their primary keys.
 BatchWriteItemResult batchWriteItem(BatchWriteItemRequest batchWriteItemRequest)
           Allows to execute a batch of Put and/or Delete Requests for many tables in a single call.
 CreateTableResult createTable(CreateTableRequest createTableRequest)
           Adds a new table to your account.
 DeleteItemResult deleteItem(DeleteItemRequest deleteItemRequest)
           Deletes a single item in a table by primary key.
 DeleteTableResult deleteTable(DeleteTableRequest deleteTableRequest)
           Deletes a table and all of its items.
 DescribeTableResult describeTable(DescribeTableRequest describeTableRequest)
           Retrieves information about the table, including the current status of the table, the primary key schema and when the table was created.
 ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request)
          Returns additional metadata for a previously executed successful, request, typically used for debugging issues where a service isn't acting as expected.
 GetItemResult getItem(GetItemRequest getItemRequest)
           Retrieves a set of Attributes for an item that matches the primary key.
 ListTablesResult listTables()
           Retrieves a paginated list of table names created by the AWS Account of the caller in the AWS Region (e.g.
 ListTablesResult listTables(ListTablesRequest listTablesRequest)
           Retrieves a paginated list of table names created by the AWS Account of the caller in the AWS Region (e.g.
 PutItemResult putItem(PutItemRequest putItemRequest)
           Creates a new item, or replaces an old item with a new item (including all the attributes).
 QueryResult query(QueryRequest queryRequest)
           Gets the values of one or more items and its attributes by primary key (composite primary key, only).
 ScanResult scan(ScanRequest scanRequest)
           Retrieves one or more items and its attributes by performing a full scan of a table.
 void setEndpoint(String endpoint, String serviceName, String regionId)
          Overrides the default endpoint for this client and explicitly provides an AWS region ID and AWS service name to use when the client calculates a signature for requests.
 UpdateItemResult updateItem(UpdateItemRequest updateItemRequest)
           Edits an existing item's attributes.
 UpdateTableResult updateTable(UpdateTableRequest updateTableRequest)
           Updates the provisioned throughput for the given table.
 
Methods inherited from class com.amazonaws.AmazonWebServiceClient
addRequestHandler, removeRequestHandler, setConfiguration, setEndpoint, shutdown
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.amazonaws.services.dynamodb.AmazonDynamoDB
setEndpoint, shutdown
 

Constructor Detail

AmazonDynamoDBClient

public AmazonDynamoDBClient()
Constructs a new client to invoke service methods on AmazonDynamoDB. A credentials provider chain will be used that searches for credentials in this order:

All service calls made using this new client object are blocking, and will not return until the service call completes.

See Also:
DefaultAWSCredentialsProvider

AmazonDynamoDBClient

public AmazonDynamoDBClient(ClientConfiguration clientConfiguration)
Constructs a new client to invoke service methods on AmazonDynamoDB. A credentials provider chain will be used that searches for credentials in this order:

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:
clientConfiguration - The client configuration options controlling how this client connects to AmazonDynamoDB (ex: proxy settings, retry counts, etc.).
See Also:
DefaultAWSCredentialsProvider

AmazonDynamoDBClient

public AmazonDynamoDBClient(AWSCredentials awsCredentials)
Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:
awsCredentials - The AWS credentials (access key ID and secret key) to use when authenticating with AWS services.

AmazonDynamoDBClient

public AmazonDynamoDBClient(AWSCredentials awsCredentials,
                            ClientConfiguration clientConfiguration)
Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials and client configuration options.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:
awsCredentials - The AWS credentials (access key ID and secret key) to use when authenticating with AWS services.
clientConfiguration - The client configuration options controlling how this client connects to AmazonDynamoDB (ex: proxy settings, retry counts, etc.).

AmazonDynamoDBClient

public AmazonDynamoDBClient(AWSCredentialsProvider awsCredentialsProvider)
Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials provider.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:
awsCredentialsProvider - The AWS credentials provider which will provide credentials to authenticate requests with AWS services.

AmazonDynamoDBClient

public AmazonDynamoDBClient(AWSCredentialsProvider awsCredentialsProvider,
                            ClientConfiguration clientConfiguration)
Constructs a new client to invoke service methods on AmazonDynamoDB using the specified AWS account credentials provider and client configuration options.

All service calls made using this new client object are blocking, and will not return until the service call completes.

Parameters:
awsCredentialsProvider - The AWS credentials provider which will provide credentials to authenticate requests with AWS services.
clientConfiguration - The client configuration options controlling how this client connects to AmazonDynamoDB (ex: proxy settings, retry counts, etc.).
Method Detail

listTables

public ListTablesResult listTables(ListTablesRequest listTablesRequest)
                            throws AmazonServiceException,
                                   AmazonClientException

Retrieves a paginated list of table names created by the AWS Account of the caller in the AWS Region (e.g. us-east-1 ).

Specified by:
listTables in interface AmazonDynamoDB
Parameters:
listTablesRequest - Container for the necessary parameters to execute the ListTables service method on AmazonDynamoDB.
Returns:
The response from the ListTables service method, as returned by AmazonDynamoDB.
Throws:
InternalServerErrorException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

query

public QueryResult query(QueryRequest queryRequest)
                  throws AmazonServiceException,
                         AmazonClientException

Gets the values of one or more items and its attributes by primary key (composite primary key, only).

Narrow the scope of the query using comparison operators on the RangeKeyValue of the composite key. Use the ScanIndexForward parameter to get results in forward or reverse order by range key.

Specified by:
query in interface AmazonDynamoDB
Parameters:
queryRequest - Container for the necessary parameters to execute the Query service method on AmazonDynamoDB.
Returns:
The response from the Query service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

batchWriteItem

public BatchWriteItemResult batchWriteItem(BatchWriteItemRequest batchWriteItemRequest)
                                    throws AmazonServiceException,
                                           AmazonClientException

Allows to execute a batch of Put and/or Delete Requests for many tables in a single call. A total of 25 requests are allowed.

There are no transaction guarantees provided by this API. It does not allow conditional puts nor does it support return values.

Specified by:
batchWriteItem in interface AmazonDynamoDB
Parameters:
batchWriteItemRequest - Container for the necessary parameters to execute the BatchWriteItem service method on AmazonDynamoDB.
Returns:
The response from the BatchWriteItem service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

updateItem

public UpdateItemResult updateItem(UpdateItemRequest updateItemRequest)
                            throws AmazonServiceException,
                                   AmazonClientException

Edits an existing item's attributes.

You can perform a conditional update (insert a new attribute name-value pair if it doesn't exist, or replace an existing name-value pair if it has certain expected attribute values).

Specified by:
updateItem in interface AmazonDynamoDB
Parameters:
updateItemRequest - Container for the necessary parameters to execute the UpdateItem service method on AmazonDynamoDB.
Returns:
The response from the UpdateItem service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
ConditionalCheckFailedException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

putItem

public PutItemResult putItem(PutItemRequest putItemRequest)
                      throws AmazonServiceException,
                             AmazonClientException

Creates a new item, or replaces an old item with a new item (including all the attributes).

If an item already exists in the specified table with the same primary key, the new item completely replaces the existing item. You can perform a conditional put (insert a new item if one with the specified primary key doesn't exist), or replace an existing item if it has certain attribute values.

Specified by:
putItem in interface AmazonDynamoDB
Parameters:
putItemRequest - Container for the necessary parameters to execute the PutItem service method on AmazonDynamoDB.
Returns:
The response from the PutItem service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
ConditionalCheckFailedException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

describeTable

public DescribeTableResult describeTable(DescribeTableRequest describeTableRequest)
                                  throws AmazonServiceException,
                                         AmazonClientException

Retrieves information about the table, including the current status of the table, the primary key schema and when the table was created.

If the table does not exist, Amazon DynamoDB returns a ResourceNotFoundException .

Specified by:
describeTable in interface AmazonDynamoDB
Parameters:
describeTableRequest - Container for the necessary parameters to execute the DescribeTable service method on AmazonDynamoDB.
Returns:
The response from the DescribeTable service method, as returned by AmazonDynamoDB.
Throws:
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

scan

public ScanResult scan(ScanRequest scanRequest)
                throws AmazonServiceException,
                       AmazonClientException

Retrieves one or more items and its attributes by performing a full scan of a table.

Provide a ScanFilter to get more specific results.

Specified by:
scan in interface AmazonDynamoDB
Parameters:
scanRequest - Container for the necessary parameters to execute the Scan service method on AmazonDynamoDB.
Returns:
The response from the Scan service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

createTable

public CreateTableResult createTable(CreateTableRequest createTableRequest)
                              throws AmazonServiceException,
                                     AmazonClientException

Adds a new table to your account.

The table name must be unique among those associated with the AWS Account issuing the request, and the AWS Region that receives the request (e.g. us-east-1 ).

The CreateTable operation triggers an asynchronous workflow to begin creating the table. Amazon DynamoDB immediately returns the state of the table ( CREATING ) until the table is in the ACTIVE state. Once the table is in the ACTIVE state, you can perform data plane operations.

Specified by:
createTable in interface AmazonDynamoDB
Parameters:
createTableRequest - Container for the necessary parameters to execute the CreateTable service method on AmazonDynamoDB.
Returns:
The response from the CreateTable service method, as returned by AmazonDynamoDB.
Throws:
ResourceInUseException
LimitExceededException
InternalServerErrorException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

updateTable

public UpdateTableResult updateTable(UpdateTableRequest updateTableRequest)
                              throws AmazonServiceException,
                                     AmazonClientException

Updates the provisioned throughput for the given table.

Setting the throughput for a table helps you manage performance and is part of the Provisioned Throughput feature of Amazon DynamoDB.

Specified by:
updateTable in interface AmazonDynamoDB
Parameters:
updateTableRequest - Container for the necessary parameters to execute the UpdateTable service method on AmazonDynamoDB.
Returns:
The response from the UpdateTable service method, as returned by AmazonDynamoDB.
Throws:
ResourceInUseException
LimitExceededException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

deleteTable

public DeleteTableResult deleteTable(DeleteTableRequest deleteTableRequest)
                              throws AmazonServiceException,
                                     AmazonClientException

Deletes a table and all of its items.

If the table is in the ACTIVE state, you can delete it. If a table is in CREATING or UPDATING states then Amazon DynamoDB returns a ResourceInUseException . If the specified table does not exist, Amazon DynamoDB returns a ResourceNotFoundException .

Specified by:
deleteTable in interface AmazonDynamoDB
Parameters:
deleteTableRequest - Container for the necessary parameters to execute the DeleteTable service method on AmazonDynamoDB.
Returns:
The response from the DeleteTable service method, as returned by AmazonDynamoDB.
Throws:
ResourceInUseException
LimitExceededException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

deleteItem

public DeleteItemResult deleteItem(DeleteItemRequest deleteItemRequest)
                            throws AmazonServiceException,
                                   AmazonClientException

Deletes a single item in a table by primary key.

You can perform a conditional delete operation that deletes the item if it exists, or if it has an expected attribute value.

Specified by:
deleteItem in interface AmazonDynamoDB
Parameters:
deleteItemRequest - Container for the necessary parameters to execute the DeleteItem service method on AmazonDynamoDB.
Returns:
The response from the DeleteItem service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
ConditionalCheckFailedException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

getItem

public GetItemResult getItem(GetItemRequest getItemRequest)
                      throws AmazonServiceException,
                             AmazonClientException

Retrieves a set of Attributes for an item that matches the primary key.

The GetItem operation provides an eventually-consistent read by default. If eventually-consistent reads are not acceptable for your application, use ConsistentRead . Although this operation might take longer than a standard read, it always returns the last updated value.

Specified by:
getItem in interface AmazonDynamoDB
Parameters:
getItemRequest - Container for the necessary parameters to execute the GetItem service method on AmazonDynamoDB.
Returns:
The response from the GetItem service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

batchGetItem

public BatchGetItemResult batchGetItem(BatchGetItemRequest batchGetItemRequest)
                                throws AmazonServiceException,
                                       AmazonClientException

Retrieves the attributes for multiple items from multiple tables using their primary keys.

The maximum number of item attributes that can be retrieved for a single operation is 100. Also, the number of items retrieved is constrained by a 1 MB the size limit. If the response size limit is exceeded or a partial result is returned due to an internal processing failure, Amazon DynamoDB returns an UnprocessedKeys value so you can retry the operation starting with the next item to get.

Amazon DynamoDB automatically adjusts the number of items returned per page to enforce this limit. For example, even if you ask to retrieve 100 items, but each individual item is 50k in size, the system returns 20 items and an appropriate UnprocessedKeys value so you can get the next page of results. If necessary, your application needs its own logic to assemble the pages of results into one set.

Specified by:
batchGetItem in interface AmazonDynamoDB
Parameters:
batchGetItemRequest - Container for the necessary parameters to execute the BatchGetItem service method on AmazonDynamoDB.
Returns:
The response from the BatchGetItem service method, as returned by AmazonDynamoDB.
Throws:
ProvisionedThroughputExceededException
InternalServerErrorException
ResourceNotFoundException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

listTables

public ListTablesResult listTables()
                            throws AmazonServiceException,
                                   AmazonClientException

Retrieves a paginated list of table names created by the AWS Account of the caller in the AWS Region (e.g. us-east-1 ).

Specified by:
listTables in interface AmazonDynamoDB
Returns:
The response from the ListTables service method, as returned by AmazonDynamoDB.
Throws:
InternalServerErrorException
AmazonClientException - If any internal errors are encountered inside the client while attempting to make the request or handle the response. For example if a network connection is not available.
AmazonServiceException - If an error response is returned by AmazonDynamoDB indicating either a problem with the data in the request, or a server side issue.

setEndpoint

public void setEndpoint(String endpoint,
                        String serviceName,
                        String regionId)
                 throws IllegalArgumentException
Overrides the default endpoint for this client and explicitly provides an AWS region ID and AWS service name to use when the client calculates a signature for requests. In almost all cases, this region ID and service name are automatically determined from the endpoint, and callers should use the simpler one-argument form of setEndpoint instead of this method.

This method is not threadsafe. Endpoints should be configured when the client is created and before any service requests are made. Changing it afterwards creates inevitable race conditions for any service requests in transit.

Callers can pass in just the endpoint (ex: "dynamodb.us-east-1.amazonaws.com/") or a full URL, including the protocol (ex: "http://dynamodb.us-east-1.amazonaws.com/"). If the protocol is not specified here, the default protocol from this client's ClientConfiguration will be used, which by default is HTTPS.

For more information on using AWS regions with the AWS SDK for Java, and a complete list of all available endpoints for all AWS services, see: http://developer.amazonwebservices.com/connect/entry.jspa?externalID=3912

Parameters:
endpoint - The endpoint (ex: "dynamodb.us-east-1.amazonaws.com/") or a full URL, including the protocol (ex: "http://dynamodb.us-east-1.amazonaws.com/") of the region specific AWS endpoint this client will communicate with.
serviceName - The name of the AWS service to use when signing requests.
regionId - The ID of the region in which this service resides.
Throws:
IllegalArgumentException - If any problems are detected with the specified endpoint.

getCachedResponseMetadata

public ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request)
Returns additional metadata for a previously executed successful, request, typically used for debugging issues where a service isn't acting as expected. This data isn't considered part of the result data returned by an operation, so it's available through this separate, diagnostic interface.

Response metadata is only cached for a limited period of time, so if you need to access this extra diagnostic information for an executed request, you should use this method to retrieve it as soon as possible after executing the request.

Specified by:
getCachedResponseMetadata in interface AmazonDynamoDB
Parameters:
request - The originally executed request
Returns:
The response metadata for the specified request, or null if none is available.


Copyright © 2010 Amazon Web Services, Inc. All Rights Reserved.