All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.amazonaws.services.simpledb.AmazonSimpleDBClient Maven / Gradle / Ivy

/*
 * Copyright 2010-2011 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License").
 * You may not use this file except in compliance with the License.
 * A copy of the License is located at
 * 
 *  http://aws.amazon.com/apache2.0
 * 
 * or in the "license" file accompanying this file. This file is distributed
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
 * express or implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */
package com.amazonaws.services.simpledb;

import org.w3c.dom.Node;

import java.util.ArrayList;
import java.util.List;
import java.util.Map.Entry;
import java.security.SignatureException;

import com.amazonaws.*;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.AWS3Signer;
import com.amazonaws.auth.QueryStringSigner;
import com.amazonaws.handlers.HandlerChainFactory;
import com.amazonaws.handlers.RequestHandler;
import com.amazonaws.http.StaxResponseHandler;
import com.amazonaws.http.DefaultErrorResponseHandler;
import com.amazonaws.http.HttpClient;
import com.amazonaws.http.HttpMethodName;
import com.amazonaws.http.HttpRequest;
import com.amazonaws.transform.Unmarshaller;
import com.amazonaws.transform.StaxUnmarshallerContext;
import com.amazonaws.transform.LegacyErrorUnmarshaller;

import com.amazonaws.services.simpledb.model.*;
import com.amazonaws.services.simpledb.model.transform.*;


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

* Amazon SimpleDB

* Amazon SimpleDB is a web service providing the core database * functions of data indexing and querying in the cloud. By offloading * the time and effort associated with building and operating a web-scale * database, SimpleDB provides developers the freedom to focus on * application development. *

*

* A traditional, clustered relational database requires a sizable * upfront capital outlay, is complex to design, and often requires * extensive and repetitive database administration. Amazon SimpleDB is * dramatically simpler, requiring no schema, automatically indexing your * data and providing a simple API for storage and access. This approach * eliminates the administrative burden of data modeling, index * maintenance, and performance tuning. Developers gain access to this * functionality within Amazon's proven computing environment, are able * to scale instantly, and pay only for what they use. *

*

* Visit * http://aws.amazon.com/simpledb/ for more information. *

*/ public class AmazonSimpleDBClient extends AmazonWebServiceClient implements AmazonSimpleDB { /** * The AWS credentials (access key ID and secret key) to use when * authenticating with AWS services. */ private AWSCredentials awsCredentials; /** * List of exception unmarshallers for all AmazonSimpleDB exceptions. */ protected final List> exceptionUnmarshallers; /** Low level client for sending requests to AWS services. */ protected final HttpClient client; /** Optional request handlers for additional request processing. */ private List requestHandlers = new ArrayList(); /** AWS signer for authenticating requests. */ private QueryStringSigner signer; /** * Constructs a new client to invoke service methods on * AmazonSimpleDB 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. * * @param awsCredentials The AWS credentials (access key ID and secret key) to use * when authenticating with AWS services. */ public AmazonSimpleDBClient(AWSCredentials awsCredentials) { this(awsCredentials, new ClientConfiguration()); } /** * Constructs a new client to invoke service methods on * AmazonSimpleDB 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. * * @param awsCredentials The AWS credentials (access key ID and secret key) to use * when authenticating with AWS services. * @param clientConfiguration The client configuration options controlling how this * client connects to AmazonSimpleDB * (ex: proxy settings, retry counts, etc.). */ public AmazonSimpleDBClient(AWSCredentials awsCredentials, ClientConfiguration clientConfiguration) { super(clientConfiguration); this.awsCredentials = awsCredentials; exceptionUnmarshallers = new ArrayList>(); exceptionUnmarshallers.add(new InvalidParameterValueExceptionUnmarshaller()); exceptionUnmarshallers.add(new NumberDomainBytesExceededExceptionUnmarshaller()); exceptionUnmarshallers.add(new NoSuchDomainExceptionUnmarshaller()); exceptionUnmarshallers.add(new NumberDomainsExceededExceptionUnmarshaller()); exceptionUnmarshallers.add(new NumberSubmittedItemsExceededExceptionUnmarshaller()); exceptionUnmarshallers.add(new RequestTimeoutExceptionUnmarshaller()); exceptionUnmarshallers.add(new InvalidQueryExpressionExceptionUnmarshaller()); exceptionUnmarshallers.add(new NumberSubmittedAttributesExceededExceptionUnmarshaller()); exceptionUnmarshallers.add(new DuplicateItemNameExceptionUnmarshaller()); exceptionUnmarshallers.add(new NumberDomainAttributesExceededExceptionUnmarshaller()); exceptionUnmarshallers.add(new InvalidNumberPredicatesExceptionUnmarshaller()); exceptionUnmarshallers.add(new TooManyRequestedAttributesExceptionUnmarshaller()); exceptionUnmarshallers.add(new InvalidNextTokenExceptionUnmarshaller()); exceptionUnmarshallers.add(new NumberItemAttributesExceededExceptionUnmarshaller()); exceptionUnmarshallers.add(new AttributeDoesNotExistExceptionUnmarshaller()); exceptionUnmarshallers.add(new MissingParameterExceptionUnmarshaller()); exceptionUnmarshallers.add(new InvalidNumberValueTestsExceptionUnmarshaller()); exceptionUnmarshallers.add(new LegacyErrorUnmarshaller()); setEndpoint("sdb.amazonaws.com"); signer = new QueryStringSigner(awsCredentials); requestHandlers = new HandlerChainFactory().newRequestHandlerChain( "/com/amazonaws/services/simpledb/request.handlers"); client = new HttpClient(clientConfiguration); } /** *

* The Select operation returns a set of attributes for * ItemNames that match the select expression. * Select is similar to the standard SQL SELECT statement. *

*

* The total size of the response cannot exceed 1 MB in total size. * Amazon SimpleDB automatically adjusts the number of items returned per * page to enforce this limit. For example, if the client asks to * retrieve 2500 items, but each individual item is 10 kB in size, the * system returns 100 items and an appropriate NextToken so * the client can access the next page of results. *

*

* For information on how to construct select expressions, see Using * Select to Create Amazon SimpleDB Queries in the Developer Guide. *

* * @param selectRequest Container for the necessary parameters to execute * the Select service method on AmazonSimpleDB. * * @return The response from the Select service method, as returned by * AmazonSimpleDB. * * @throws InvalidParameterValueException * @throws InvalidQueryExpressionException * @throws RequestTimeoutException * @throws InvalidNumberPredicatesException * @throws NoSuchDomainException * @throws InvalidNextTokenException * @throws TooManyRequestedAttributesException * @throws MissingParameterException * @throws InvalidNumberValueTestsException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public SelectResult select(SelectRequest selectRequest) throws AmazonServiceException, AmazonClientException { Request request = new SelectRequestMarshaller().marshall(selectRequest); return invoke(request, new SelectResultStaxUnmarshaller()); } /** *

* The PutAttributes operation creates or replaces attributes in an * item. The client may specify new attributes using a combination of the * Attribute.X.Name and Attribute.X.Value * parameters. The client specifies the first attribute by the parameters * Attribute.0.Name and Attribute.0.Value , * the second attribute by the parameters Attribute.1.Name * and Attribute.1.Value , and so on. *

*

* Attributes are uniquely identified in an item by their name/value * combination. For example, a single item can have the attributes * { "first_name", "first_value" } and { "first_name", * second_value" } . However, it cannot have two attribute * instances where both the Attribute.X.Name and * Attribute.X.Value are the same. *

*

* Optionally, the requestor can supply the Replace * parameter for each individual attribute. Setting this value to * true causes the new attribute value to replace the * existing attribute value(s). For example, if an item has the * attributes { 'a', '1' } , * * { 'b', '2'} and { 'b', '3' * } and the requestor calls PutAttributes using the * attributes { 'b', '4' } with the Replace * parameter set to true, the final attributes of the item are changed to * { 'a', '1' } and { 'b', '4' } , which * replaces the previous values of the 'b' attribute with the new value. *

*

* NOTE: Using PutAttributes to replace attribute values that do * not exist will not result in an error response. *

*

* You cannot specify an empty string as an attribute name. *

*

* Because Amazon SimpleDB makes multiple copies of client data and uses * an eventual consistency update model, an immediate GetAttributes or * Select operation (read) immediately after a DeleteAttributes operation * (write) might not return the updated data. *

*

* The following limitations are enforced for this operation: *

    *
  • 256 total attribute name-value pairs per item
  • *
  • One billion attributes per domain
  • *
  • 10 GB of total user data storage per domain
  • * *
* *

* * @param putAttributesRequest Container for the necessary parameters to * execute the PutAttributes service method on AmazonSimpleDB. * * @throws InvalidParameterValueException * @throws NumberDomainBytesExceededException * @throws NumberDomainAttributesExceededException * @throws NoSuchDomainException * @throws NumberItemAttributesExceededException * @throws AttributeDoesNotExistException * @throws MissingParameterException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public void putAttributes(PutAttributesRequest putAttributesRequest) throws AmazonServiceException, AmazonClientException { Request request = new PutAttributesRequestMarshaller().marshall(putAttributesRequest); invoke(request, null); } /** *

* Performs multiple DeleteAttributes operations in a single call, which * reduces round trips and latencies. This enables Amazon SimpleDB to * optimize requests, which generally yields better throughput. *

*

* NOTE: If you specify BatchDeleteAttributes without attributes * or values, all the attributes for the item are deleted. * BatchDeleteAttributes is an idempotent operation; running it multiple * times on the same item or attribute doesn't result in an error. The * BatchDeleteAttributes operation succeeds or fails in its entirety. * There are no partial deletes. You can execute multiple * BatchDeleteAttributes operations and other operations in parallel. * However, large numbers of concurrent BatchDeleteAttributes calls can * result in Service Unavailable (503) responses. This operation is * vulnerable to exceeding the maximum URL size when making a REST * request using the HTTP GET method. This operation does not support * conditions using Expected.X.Name, Expected.X.Value, or * Expected.X.Exists. *

*

* The following limitations are enforced for this operation: *

    *
  • 1 MB request size
  • *
  • 25 item limit per BatchDeleteAttributes operation
  • * *
* *

* * @param batchDeleteAttributesRequest Container for the necessary * parameters to execute the BatchDeleteAttributes service method on * AmazonSimpleDB. * * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public void batchDeleteAttributes(BatchDeleteAttributesRequest batchDeleteAttributesRequest) throws AmazonServiceException, AmazonClientException { Request request = new BatchDeleteAttributesRequestMarshaller().marshall(batchDeleteAttributesRequest); invoke(request, null); } /** *

* The DeleteDomain operation deletes a domain. Any items * (and their attributes) in the domain are deleted as well. The * DeleteDomain operation might take 10 or more seconds to * complete. *

*

* NOTE: Running DeleteDomain on a domain that does not exist or * running the function multiple times using the same domain name will * not result in an error response. *

* * @param deleteDomainRequest Container for the necessary parameters to * execute the DeleteDomain service method on AmazonSimpleDB. * * @throws MissingParameterException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public void deleteDomain(DeleteDomainRequest deleteDomainRequest) throws AmazonServiceException, AmazonClientException { Request request = new DeleteDomainRequestMarshaller().marshall(deleteDomainRequest); invoke(request, null); } /** *

* The CreateDomain operation creates a new domain. The * domain name should be unique among the domains associated with the * Access Key ID provided in the request. The CreateDomain * operation may take 10 or more seconds to complete. *

*

* NOTE: CreateDomain is an idempotent operation; running it * multiple times using the same domain name will not result in an error * response. *

*

* The client can create up to 100 domains per account. *

*

* If the client requires additional domains, go to * http://aws.amazon.com/contact-us/simpledb-limit-request/ . *

* * @param createDomainRequest Container for the necessary parameters to * execute the CreateDomain service method on AmazonSimpleDB. * * @throws InvalidParameterValueException * @throws NumberDomainsExceededException * @throws MissingParameterException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public void createDomain(CreateDomainRequest createDomainRequest) throws AmazonServiceException, AmazonClientException { Request request = new CreateDomainRequestMarshaller().marshall(createDomainRequest); invoke(request, null); } /** *

* Deletes one or more attributes associated with an item. If all * attributes of the item are deleted, the item is deleted. *

*

* NOTE: If DeleteAttributes is called without being passed any * attributes or values specified, all the attributes for the item are * deleted. *

*

* DeleteAttributes is an idempotent operation; running it * multiple times on the same item or attribute does not result in an * error response. *

*

* Because Amazon SimpleDB makes multiple copies of item data and uses * an eventual consistency update model, performing a GetAttributes or * Select operation (read) immediately after a * DeleteAttributes or PutAttributes operation (write) might * not return updated item data. *

* * @param deleteAttributesRequest Container for the necessary parameters * to execute the DeleteAttributes service method on AmazonSimpleDB. * * @throws InvalidParameterValueException * @throws NoSuchDomainException * @throws AttributeDoesNotExistException * @throws MissingParameterException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public void deleteAttributes(DeleteAttributesRequest deleteAttributesRequest) throws AmazonServiceException, AmazonClientException { Request request = new DeleteAttributesRequestMarshaller().marshall(deleteAttributesRequest); invoke(request, null); } /** *

* The ListDomains operation lists all domains associated * with the Access Key ID. It returns domain names up to the limit set by * MaxNumberOfDomains. A NextToken is returned if there are more than * MaxNumberOfDomains domains. Calling * ListDomains successive times with the * NextToken provided by the operation returns up to * MaxNumberOfDomains more domain names with each successive * operation call. *

* * @param listDomainsRequest Container for the necessary parameters to * execute the ListDomains service method on AmazonSimpleDB. * * @return The response from the ListDomains service method, as returned * by AmazonSimpleDB. * * @throws InvalidParameterValueException * @throws InvalidNextTokenException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public ListDomainsResult listDomains(ListDomainsRequest listDomainsRequest) throws AmazonServiceException, AmazonClientException { Request request = new ListDomainsRequestMarshaller().marshall(listDomainsRequest); return invoke(request, new ListDomainsResultStaxUnmarshaller()); } /** *

* Returns all of the attributes associated with the specified item. * Optionally, the attributes returned can be limited to one or more * attributes by specifying an attribute name parameter. *

*

* If the item does not exist on the replica that was accessed for this * operation, an empty set is returned. The system does not return an * error as it cannot guarantee the item does not exist on other * replicas. *

*

* NOTE: If GetAttributes is called without being passed any * attribute names, all the attributes for the item are returned. *

* * @param getAttributesRequest Container for the necessary parameters to * execute the GetAttributes service method on AmazonSimpleDB. * * @return The response from the GetAttributes service method, as * returned by AmazonSimpleDB. * * @throws InvalidParameterValueException * @throws NoSuchDomainException * @throws MissingParameterException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public GetAttributesResult getAttributes(GetAttributesRequest getAttributesRequest) throws AmazonServiceException, AmazonClientException { Request request = new GetAttributesRequestMarshaller().marshall(getAttributesRequest); return invoke(request, new GetAttributesResultStaxUnmarshaller()); } /** *

* The BatchPutAttributes operation creates or replaces * attributes within one or more items. By using this operation, the * client can perform multiple PutAttribute operation with a single call. * This helps yield savings in round trips and latencies, enabling * Amazon SimpleDB to optimize requests and generally produce better * throughput. *

*

* The client may specify the item name with the * Item.X.ItemName parameter. The client may specify new * attributes using a combination of the * Item.X.Attribute.Y.Name and * Item.X.Attribute.Y.Value parameters. The client may * specify the first attribute for the first item using the parameters * Item.0.Attribute.0.Name and * Item.0.Attribute.0.Value , * and for the second attribute for the first item by the parameters * Item.0.Attribute.1.Name and * Item.0.Attribute.1.Value , * and so on. *

*

* Attributes are uniquely identified within an item by their name/value * combination. For example, a single item can have the attributes * { "first_name", "first_value" } and { "first_name", * "second_value" } . * However, it cannot have two attribute instances where both the * Item.X.Attribute.Y.Name and * Item.X.Attribute.Y.Value are the same. *

*

* Optionally, the requester can supply the Replace * parameter for each individual value. Setting this value to * true will cause the new attribute values to replace the * existing attribute values. For example, if an item I has * the attributes { 'a', '1' }, { 'b', '2'} and { 'b', * '3' } and the requester does a BatchPutAttributes of * {'I', 'b', '4' } with the Replace parameter set to true, * the final attributes of the item will be { 'a', '1' } and * { 'b', '4' } , * replacing the previous values of the 'b' attribute with the new * value. *

*

* NOTE: You cannot specify an empty string as an item or as an * attribute name. The BatchPutAttributes operation succeeds or fails in * its entirety. There are no partial puts. *

*

* IMPORTANT: This operation is vulnerable to exceeding the * maximum URL size when making a REST request using the HTTP GET method. * This operation does not support conditions using Expected.X.Name, * Expected.X.Value, or Expected.X.Exists. *

*

* You can execute multiple BatchPutAttributes operations * and other operations in parallel. However, large numbers of concurrent * BatchPutAttributes calls can result in Service * Unavailable (503) responses. *

*

* The following limitations are enforced for this operation: *

    *
  • 256 attribute name-value pairs per item
  • *
  • 1 MB request size
  • *
  • 1 billion attributes per domain
  • *
  • 10 GB of total user data storage per domain
  • *
  • 25 item limit per BatchPutAttributes operation
  • * *
* *

* * @param batchPutAttributesRequest Container for the necessary * parameters to execute the BatchPutAttributes service method on * AmazonSimpleDB. * * @throws DuplicateItemNameException * @throws InvalidParameterValueException * @throws NumberDomainBytesExceededException * @throws NumberSubmittedItemsExceededException * @throws NumberSubmittedAttributesExceededException * @throws NumberDomainAttributesExceededException * @throws NoSuchDomainException * @throws NumberItemAttributesExceededException * @throws MissingParameterException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public void batchPutAttributes(BatchPutAttributesRequest batchPutAttributesRequest) throws AmazonServiceException, AmazonClientException { Request request = new BatchPutAttributesRequestMarshaller().marshall(batchPutAttributesRequest); invoke(request, null); } /** *

* Returns information about the domain, including when the domain was * created, the number of items and attributes in the domain, and the * size of the attribute names and values. *

* * @param domainMetadataRequest Container for the necessary parameters to * execute the DomainMetadata service method on AmazonSimpleDB. * * @return The response from the DomainMetadata service method, as * returned by AmazonSimpleDB. * * @throws NoSuchDomainException * @throws MissingParameterException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public DomainMetadataResult domainMetadata(DomainMetadataRequest domainMetadataRequest) throws AmazonServiceException, AmazonClientException { Request request = new DomainMetadataRequestMarshaller().marshall(domainMetadataRequest); return invoke(request, new DomainMetadataResultStaxUnmarshaller()); } /** *

* The ListDomains operation lists all domains associated * with the Access Key ID. It returns domain names up to the limit set by * MaxNumberOfDomains. A NextToken is returned if there are more than * MaxNumberOfDomains domains. Calling * ListDomains successive times with the * NextToken provided by the operation returns up to * MaxNumberOfDomains more domain names with each successive * operation call. *

* * @return The response from the ListDomains service method, as returned * by AmazonSimpleDB. * * @throws InvalidParameterValueException * @throws InvalidNextTokenException * * @throws 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. * @throws AmazonServiceException * If an error response is returned by AmazonSimpleDB indicating * either a problem with the data in the request, or a server side issue. */ public ListDomainsResult listDomains() throws AmazonServiceException, AmazonClientException { return listDomains(new ListDomainsRequest()); } /** * 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. * * @param request * The originally executed request * * @return The response metadata for the specified request, or null if none * is available. */ public SimpleDBResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request) { ResponseMetadata metadata = client.getResponseMetadataForRequest(request); if (metadata != null) return new SimpleDBResponseMetadata(metadata); else return null; } private X invoke(Request request, Unmarshaller unmarshaller) { request.setEndpoint(endpoint); for (Entry entry : request.getOriginalRequest().copyPrivateRequestParameters().entrySet()) { request.addParameter(entry.getKey(), entry.getValue()); } // Apply any additional service specific request handlers that need to be run if (requestHandlers != null) { for (RequestHandler requestHandler : requestHandlers) { request = requestHandler.handleRequest(request); } } try { signer.sign(request); } catch (SignatureException e) { throw new AmazonServiceException("Unable to sign request", e); } HttpRequest httpRequest = convertToHttpRequest(request, HttpMethodName.POST); StaxResponseHandler responseHandler = new com.amazonaws.services.simpledb.internal.SimpleDBStaxResponseHandler(unmarshaller); DefaultErrorResponseHandler errorResponseHandler = new DefaultErrorResponseHandler(exceptionUnmarshallers); return (X)client.execute(httpRequest, responseHandler, errorResponseHandler); } }





© 2015 - 2025 Weber Informatics LLC | Privacy Policy