com.microsoft.azure.documentdb.DocumentClient Maven / Gradle / Ivy

Go to download
/*
 * Copyright (c) Microsoft Corporation.  All rights reserved.
 */

package com.microsoft.azure.documentdb;

import java.io.IOException;
import java.io.InputStream;
import java.io.UnsupportedEncodingException;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URLEncoder;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.BlockingQueue;
import java.util.concurrent.CancellationException;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Future;
import java.util.concurrent.SynchronousQueue;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;

import com.microsoft.azure.documentdb.internal.BridgeInternal;
import com.microsoft.azure.documentdb.internal.RefreshAuthTokenDelegate;
import org.apache.commons.lang3.StringUtils;
import org.apache.http.client.HttpClient;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import org.json.JSONObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.microsoft.azure.documentdb.internal.AbstractDocumentServiceRequest;
import com.microsoft.azure.documentdb.internal.AuthorizationTokenProvider;
import com.microsoft.azure.documentdb.internal.BaseAuthorizationTokenProvider;
import com.microsoft.azure.documentdb.internal.BaseDatabaseAccountConfigurationProvider;
import com.microsoft.azure.documentdb.internal.CollectionCacheInternal;
import com.microsoft.azure.documentdb.internal.DatabaseAccountConfigurationProvider;
import com.microsoft.azure.documentdb.internal.DocumentServiceRequest;
import com.microsoft.azure.documentdb.internal.DocumentServiceResponse;
import com.microsoft.azure.documentdb.internal.EndpointManager;
import com.microsoft.azure.documentdb.internal.GatewayProxy;
import com.microsoft.azure.documentdb.internal.HttpConstants;
import com.microsoft.azure.documentdb.internal.OperationType;
import com.microsoft.azure.documentdb.internal.PathParser;
import com.microsoft.azure.documentdb.internal.Paths;
import com.microsoft.azure.documentdb.internal.QueryCompatibilityMode;
import com.microsoft.azure.documentdb.internal.ResourceType;
import com.microsoft.azure.documentdb.internal.RetryCreateDocumentDelegate;
import com.microsoft.azure.documentdb.internal.RetryRequestDelegate;
import com.microsoft.azure.documentdb.internal.RetryUtility;
import com.microsoft.azure.documentdb.internal.RuntimeConstants;
import com.microsoft.azure.documentdb.internal.ServiceJNIWrapper;
import com.microsoft.azure.documentdb.internal.SessionContainer;
import com.microsoft.azure.documentdb.internal.SessionTokenHelper;
import com.microsoft.azure.documentdb.internal.StoreModel;
import com.microsoft.azure.documentdb.internal.UserAgentContainer;
import com.microsoft.azure.documentdb.internal.Utils;
import com.microsoft.azure.documentdb.internal.directconnectivity.AddressCache;
import com.microsoft.azure.documentdb.internal.directconnectivity.GlobalAddressResolver;
import com.microsoft.azure.documentdb.internal.directconnectivity.HttpClientFactory;
import com.microsoft.azure.documentdb.internal.directconnectivity.HttpTransportClient;
import com.microsoft.azure.documentdb.internal.directconnectivity.ServerStoreModel;
import com.microsoft.azure.documentdb.internal.directconnectivity.TransportClient;
import com.microsoft.azure.documentdb.internal.query.PartitionedQueryExecutionInfo;
import com.microsoft.azure.documentdb.internal.query.QueryPartitionProvider;
import com.microsoft.azure.documentdb.internal.routing.ClientCollectionCache;
import com.microsoft.azure.documentdb.internal.routing.CollectionCache;
import com.microsoft.azure.documentdb.internal.routing.PartitionKeyInternal;
import com.microsoft.azure.documentdb.internal.routing.PartitionKeyRangeCache;
import com.microsoft.azure.documentdb.internal.routing.PartitionKeyRangeIdentity;
import com.microsoft.azure.documentdb.internal.routing.RoutingMapProvider;
import com.microsoft.azure.documentdb.internal.routing.RoutingMapProviderHelper;

/**
 * Provides a client-side logical representation of the Azure Cosmos DB service. This client is used to configure and
 * execute requests against the service.
 * 
 * The service client encapsulates the endpoint and credentials used to access the Azure Cosmos DB service.
 */
public class DocumentClient implements AutoCloseable, CollectionCacheInternal {

    @Deprecated
    protected static final String PartitionResolverErrorMessage = "Couldn't find any partition resolvers for the database link provided. Ensure that the link you used when registering the partition resolvers matches the link provided or you need to register both types of database link(self link as well as ID based link).";
    private static final Logger logger = LoggerFactory.getLogger(DocumentClient.class);

    private URI serviceEndpoint;
    private String masterKey;
    private Map resourceTokens;
    private ConnectionPolicy connectionPolicy;
    private GatewayProxy gatewayProxy;
    private SessionContainer sessionContainer;
    private ConsistencyLevel desiredConsistencyLevel;
    private EndpointManager globalEndpointManager;
    @SuppressWarnings("deprecation")
    private ConcurrentHashMap partitionResolvers;
    private StoreModel storeModel;
    private GlobalAddressResolver globalAddressResolver;
    private TransportClient transportClient;
    private AuthorizationTokenProvider authorizationTokenProvider;
    private DatabaseAccountConfigurationProvider databaseAccountConfigurationProvider;
    private ClientCollectionCache collectionCache;
    private PartitionKeyRangeCache partitionKeyRangeCache;
    private PoolingHttpClientConnectionManager poolingHttpClientConnectionManager;
    private ExecutorService executorService;
    private ObjectMapper objectMapper;
    private boolean useMultipleWriteLocations;

    /**
     * Compatibility mode:
     * Allows to specify compatibility mode used by client when making query requests. Should be removed when
     * application/sql is no longer supported.
     */
    private QueryCompatibilityMode queryCompatibilityMode = QueryCompatibilityMode.Default;

    /**
     * Initializes a new instance of the DocumentClient class using the specified Azure Cosmos DB service endpoint and keys.
     *
     * @param serviceEndpoint         the URI of the service end point.
     * @param masterKey               the master key.
     * @param connectionPolicy        the connection policy.
     * @param desiredConsistencyLevel the desired consistency level.
     */
    public DocumentClient(String serviceEndpoint,
            String masterKey,
            ConnectionPolicy connectionPolicy,
            ConsistencyLevel desiredConsistencyLevel) {
        this(serviceEndpoint, masterKey, null, connectionPolicy, desiredConsistencyLevel, null, null, new UserAgentContainer());
    }

    /**
     * Initializes a new instance of the DocumentClient class using the specified Azure Cosmos DB service endpoint and keys.
     *
     * @param serviceEndpoint         the URI of the service end point.
     * @param masterKey               the master key.
     * @param objectMapper            the custom objectMapper
     * @param connectionPolicy        the connection policy.
     * @param desiredConsistencyLevel the desired consistency level.
     */
    public DocumentClient(String serviceEndpoint,
            String masterKey,
            ObjectMapper objectMapper,
            ConnectionPolicy connectionPolicy,
            ConsistencyLevel desiredConsistencyLevel) {
        this(serviceEndpoint, masterKey, objectMapper, connectionPolicy, desiredConsistencyLevel, null, null, new UserAgentContainer());
    }

    /**
     * Initializes a new instance of the Microsoft.Azure.Documents.Client.DocumentClient class using the specified
     * Azure Cosmos DB service endpoint and permissions.
     *
     * @param serviceEndpoint         the URI of the service end point.
     * @param permissionFeed          the permission feed.
     * @param connectionPolicy        the connection policy.
     * @param desiredConsistencyLevel the desired consistency level.
     */
    public DocumentClient(String serviceEndpoint,
            List permissionFeed,
            ConnectionPolicy connectionPolicy,
            ConsistencyLevel desiredConsistencyLevel) {
        this(serviceEndpoint, permissionFeed, null, connectionPolicy, desiredConsistencyLevel, new UserAgentContainer());
    }

    /**
     * Initializes a new instance of the Microsoft.Azure.Documents.Client.DocumentClient class using the specified
     * Azure Cosmos DB service endpoint and permissions.
     *
     * @param serviceEndpoint         the URI of the service end point.
     * @param permissionFeed          the permission feed.
     * @param objectMapper            the custom objectMapper
     * @param connectionPolicy        the connection policy.
     * @param desiredConsistencyLevel the desired consistency level.
     */
    public DocumentClient(String serviceEndpoint,
            List permissionFeed,
            ObjectMapper objectMapper,
            ConnectionPolicy connectionPolicy,
            ConsistencyLevel desiredConsistencyLevel) {
        this(serviceEndpoint, permissionFeed, objectMapper, connectionPolicy, desiredConsistencyLevel, new UserAgentContainer());
    }

    DocumentClient(String serviceEndpoint,
            List permissionFeed,
            ObjectMapper objectMapper,
            ConnectionPolicy connectionPolicy,
            ConsistencyLevel desiredConsistencyLevel,
            UserAgentContainer userAgentContainer) {
        URI uri = null;
        try {
            uri = new URI(serviceEndpoint);
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid serviceEndPoint.", e);
        }

        this.resourceTokens = new HashMap();
        this.objectMapper = objectMapper != null ?  objectMapper: new ObjectMapper();

        for (Permission permission : permissionFeed) {
            String[] segments = StringUtils.split(permission.getResourceLink(), '/');

            if (segments.length <= 0) {
                throw new IllegalArgumentException("link");
            }

            String resourceId = segments[segments.length - 1];
            this.resourceTokens.put(resourceId, permission.getToken());
        }

        this.initialize(uri, connectionPolicy, desiredConsistencyLevel, userAgentContainer, null);
    }

    DocumentClient(String serviceEndpoint, String masterKey, ObjectMapper objectMapper, ConnectionPolicy connectionPolicy,
            ConsistencyLevel desiredConsistencyLevel, ConcurrentHashMap addressCaches,
            TransportClient transportClient, UserAgentContainer userAgentContainer) {
        URI uri = null;
        try {
            uri = new URI(serviceEndpoint);
        } catch (URISyntaxException e) {
            throw new IllegalArgumentException("Invalid serviceEndPoint.", e);
        }

        if (StringUtils.isEmpty(masterKey)) {
            throw new IllegalArgumentException("Invalid authentication key.");
        }

        this.masterKey = masterKey;
        this.objectMapper = objectMapper != null ?  objectMapper: new ObjectMapper();

        this.transportClient = transportClient;
        this.initialize(uri, connectionPolicy, desiredConsistencyLevel, userAgentContainer, addressCaches);
    }

    private static String serializeProcedureParams(Object[] objectArray, ObjectMapper objectMapper) {
        String[] stringArray = new String[objectArray.length];

        for (int i = 0; i < objectArray.length; ++i) {
            Object object = objectArray[i];
            if (object instanceof JsonSerializable) {
                stringArray[i] = ((JsonSerializable) object).toJson();
            } else if (object instanceof JSONObject){
                stringArray[i] = object.toString();
            } else {

                // POJO, number, String or Boolean
                try {
                    stringArray[i] = objectMapper.writeValueAsString(object);
                } catch (IOException e) {
                    throw new IllegalArgumentException("Can't serialize the object into the json string", e);
                }
            }
        }

        return String.format("[%s]", StringUtils.join(stringArray, ","));
    }

    static void validateResource(Resource resource) {
        if (!StringUtils.isEmpty(resource.getId())) {
            if (resource.getId().indexOf('/') != -1 || resource.getId().indexOf('\\') != -1 ||
                    resource.getId().indexOf('?') != -1 || resource.getId().indexOf('#') != -1) {
                throw new IllegalArgumentException("Id contains illegal chars.");
            }

            if (resource.getId().endsWith(" ")) {
                throw new IllegalArgumentException("Id ends with a space.");
            }
        }
    }

    @SuppressWarnings("deprecation") // use of PartitionResolver is deprecated.
    private void initialize(URI serviceEndpoint,
            ConnectionPolicy connectionPolicy,
            ConsistencyLevel desiredConsistencyLevel,
            UserAgentContainer userAgentContainer,
            ConcurrentHashMap addressCaches) {
        logger.info("Initializing DocumentClient with"
                + " serviceEndpoint [{}], ConnectionPolicy [{}], ConsistencyLevel [{}]",
                serviceEndpoint, connectionPolicy, desiredConsistencyLevel);
        this.serviceEndpoint = serviceEndpoint;

        if (connectionPolicy != null) {
            this.connectionPolicy = connectionPolicy;
        } else {
            this.connectionPolicy = new ConnectionPolicy();
        }

        this.desiredConsistencyLevel = desiredConsistencyLevel;

        String userAgentSuffix = this.connectionPolicy.getUserAgentSuffix();
        if (userAgentSuffix != null && userAgentSuffix.length() > 0) {
            userAgentContainer.setSuffix(userAgentSuffix);
        }

        this.executorService = new DocumentDBThreadPoolExecutor(0, Integer.MAX_VALUE,
                60L, TimeUnit.SECONDS,
                new SynchronousQueue());

        this.poolingHttpClientConnectionManager = HttpClientFactory.createConnectionManager(
                this.connectionPolicy.getMaxPoolSize(),
                this.connectionPolicy.getIdleConnectionTimeout(),
                this.connectionPolicy.getRequestTimeout());

        HttpClient httpClient = createHttpClient(this.poolingHttpClientConnectionManager,
                this.connectionPolicy.getRequestTimeout());
        
        HttpClient mediaHttpClient = HttpClientFactory.createHttpClient(this.poolingHttpClientConnectionManager,
                this.connectionPolicy.getMediaRequestTimeout());

        this.globalEndpointManager = new GlobalEndpointManager(this);
        // use of PartitionResolver is deprecated.
        this.partitionResolvers = new ConcurrentHashMap();
        this.authorizationTokenProvider = new BaseAuthorizationTokenProvider(this.masterKey, this.resourceTokens);
        this.collectionCache = createClientCollectionCache(this, this.executorService);
        this.partitionKeyRangeCache = createPartitionKeyRangeCache();

        this.sessionContainer = new SessionContainer(
                this.serviceEndpoint.getHost(),
                this.collectionCache,
                this.partitionKeyRangeCache);

        this.gatewayProxy = createGatewayProxy(
                this.connectionPolicy,
                desiredConsistencyLevel,
                this.queryCompatibilityMode,
                this.masterKey,
                this.resourceTokens,
                userAgentContainer,
                this.globalEndpointManager,
                httpClient,
                mediaHttpClient,
                this.sessionContainer);

        this.databaseAccountConfigurationProvider = createBaseDatabaseAccountConfigurationProvider(
                this.desiredConsistencyLevel, this.globalEndpointManager);
        if (this.connectionPolicy.getConnectionMode() == ConnectionMode.DirectHttps) {
            if (this.globalAddressResolver == null) {
                this.globalAddressResolver = new GlobalAddressResolver(this.serviceEndpoint.toString(),
                                addressCaches,
                                this.connectionPolicy,
                                this.collectionCache,
                                this.partitionKeyRangeCache,
                                userAgentContainer,
                                this.authorizationTokenProvider,
                                httpClient,
                                this.globalEndpointManager,
                                this,
                                this.executorService);
            }

            if (this.transportClient == null) {
                this.transportClient = createHttpTransportClient(this.connectionPolicy, userAgentContainer);
            }

            this.storeModel = createServerStoreModel(
                    this.transportClient,
                    this.globalAddressResolver,
                    this.sessionContainer,
                    this.databaseAccountConfigurationProvider,
                    this.authorizationTokenProvider,
                    this.executorService,
                    this.connectionPolicy.getRetryOptions(),
                    this.useMultipleWriteLocations && this.desiredConsistencyLevel != ConsistencyLevel.Strong);
        } else {
            this.storeModel = this.gatewayProxy;
        }
    }

    HttpClient createHttpClient(PoolingHttpClientConnectionManager poolingHttpClientConnectionManager,
            int requestTimeout) {
        return HttpClientFactory.createHttpClient(poolingHttpClientConnectionManager, requestTimeout);
    }

    DatabaseAccountConfigurationProvider createBaseDatabaseAccountConfigurationProvider(
            ConsistencyLevel desiredConsistencyLevel, EndpointManager globalEndpointManager) {
        return new BaseDatabaseAccountConfigurationProvider(desiredConsistencyLevel, globalEndpointManager);
    }

    ClientCollectionCache createClientCollectionCache(DocumentClient documentClient, ExecutorService executorService) {
        return new ClientCollectionCache(documentClient, executorService);
    }

    GatewayProxy createGatewayProxy(ConnectionPolicy connectionPolicy, ConsistencyLevel desiredConsistencyLevel,
            QueryCompatibilityMode queryCompatibilityMode, String masterKey, Map resourceTokens,
            UserAgentContainer userAgentContainer, EndpointManager globalEndpointManager, HttpClient httpClient,
            HttpClient mediaHttpClient, SessionContainer sessionContainer) {
        return new GatewayProxy(connectionPolicy, desiredConsistencyLevel, queryCompatibilityMode, masterKey,
                resourceTokens, userAgentContainer, globalEndpointManager, httpClient, mediaHttpClient,
                sessionContainer);
    }

    StoreModel createServerStoreModel(TransportClient transportClient,
            GlobalAddressResolver globalAddressResolver,
            SessionContainer sessionContainer,
            DatabaseAccountConfigurationProvider databaseAccountConfigurationProvider,
            AuthorizationTokenProvider authorizationTokenProvider,
            ExecutorService executorService,
            RetryOptions retryOptions,
            boolean useMultipleWriteLocations) {

	    RefreshAuthTokenDelegate refreshAuthTokenDelegate = new RefreshAuthTokenDelegate() {
		    @Override
		    public void apply(DocumentServiceRequest request){
			    putMoreContentIntoDocumentServiceRequest(request, null);
		    }
	    };

        return new ServerStoreModel(transportClient, globalAddressResolver, sessionContainer,
                databaseAccountConfigurationProvider, authorizationTokenProvider, executorService,
                refreshAuthTokenDelegate, retryOptions, useMultipleWriteLocations);
    }

    HttpTransportClient createHttpTransportClient(ConnectionPolicy policy,
            UserAgentContainer userAgentContainer) {
        return new HttpTransportClient(this.connectionPolicy, userAgentContainer);
    }

    @Deprecated
    public void registerPartitionResolver(String databaseLink, PartitionResolver partitionResolver)
            throws DocumentClientException {
        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }
        if (partitionResolver == null) {
            throw new IllegalArgumentException("partitionResolver");
        }

        this.partitionResolvers.put(Utils.trimBeginingAndEndingSlashes(databaseLink), partitionResolver);
    }

    @Deprecated
    protected PartitionResolver getPartitionResolver(String databaseLink) {
        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }
        return this.partitionResolvers.get(Utils.trimBeginingAndEndingSlashes(databaseLink));
    }

    QueryCompatibilityMode getQueryCompatiblityMode() {
        return this.queryCompatibilityMode;
    }

    /**
     * Gets the default service endpoint as passed in by the user during construction.
     *
     * @return the service endpoint URI
     */
    public URI getServiceEndpoint() {
        return this.serviceEndpoint;
    }

    /**
     * Gets the current write endpoint chosen based on availability and preference.
     *
     * @return the write endpoint URI
     */
    public URI getWriteEndpoint() {
        return this.globalEndpointManager.getWriteEndpoint();
    }

    /**
     * Gets the current read endpoint chosen based on availability and preference.
     *
     * @return the read endpoint URI
     */
    public URI getReadEndpoint() {
        return this.globalEndpointManager.getReadEndpoint();
    }

    public ConnectionPolicy getConnectionPolicy() {
        return this.connectionPolicy;
    }

    EndpointManager getEndpointManager() {
        return this.globalEndpointManager;
    }

    void setEndpointManager(EndpointManager endpointManager) {
        this.globalEndpointManager = endpointManager;
    }

    RoutingMapProvider getPartitionKeyRangeCache() {
        return this.partitionKeyRangeCache;
    }

    CollectionCache getCollectionCache() {
        return this.collectionCache;
    }

    ExecutorService getExecutorService() {
        return this.executorService;
    }

    String getSessionToken(String collectionLink) {
        return this.sessionContainer.resolveGlobalSessionToken(collectionLink);
    }

    PoolingHttpClientConnectionManager getPoolHttpClientConnectionManager() {
        return this.poolingHttpClientConnectionManager;
    }

    // used by unit test to mock gateway proxy.
    void setGatewayProxyOverride(GatewayProxy proxyOverride) {
        this.gatewayProxy = proxyOverride;
        if (this.connectionPolicy.getConnectionMode() != ConnectionMode.DirectHttps) {
            this.storeModel = proxyOverride;
        }
    }

    // used by unit test to mock server store model.
    void setStoreModel(StoreModel storeModel) {
        if (this.connectionPolicy.getConnectionMode() == ConnectionMode.DirectHttps) {
            this.storeModel = storeModel;
        }
    }

    /**
     * Creates a database.
     *
     * @param database the database.
     * @param options  the request options.
     * @return the resource response with the created database.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse createDatabase(Database database, RequestOptions options)
            throws DocumentClientException {
        if (database == null) {
            throw new IllegalArgumentException("Database");
        }

        logger.debug("Creating a Database. id: [{}]", database.getId());
        DocumentClient.validateResource(database);

        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Create,
                ResourceType.Database,
                Paths.DATABASES_ROOT,
                database,
                requestHeaders);
        return new ResourceResponse(this.doCreate(request), Database.class);
    }

    /**
     * Deletes a database.
     *
     * @param databaseLink the database link.
     * @param options      the request options.
     * @return the resource response.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse deleteDatabase(String databaseLink, RequestOptions options)
            throws DocumentClientException {
        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }

        logger.debug("Deleting a Database. databaseLink: [{}]", databaseLink);
        String path = Utils.joinPath(databaseLink, null);
        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Delete,
                ResourceType.Database,
                path,
                requestHeaders);
        return new ResourceResponse(this.doDelete(request), Database.class);
    }

    /**
     * Reads a database.
     *
     * @param databaseLink the database link.
     * @param options      the request options.
     * @return the resource response with the read database.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse readDatabase(String databaseLink, RequestOptions options)
            throws DocumentClientException {
        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }

        logger.debug("Reading a Database. databaseLink: [{}]", databaseLink);
        String path = Utils.joinPath(databaseLink, null);
        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Read,
                ResourceType.Database,
                path,
                requestHeaders);
        return new ResourceResponse(this.doRead(request), Database.class);
    }

    /**
     * Reads all databases.
     *
     * @param options the feed options.
     * @return the feed response with the read databases.
     */
    public FeedResponse readDatabases(FeedOptions options) {
        logger.debug("Reading Databases.");
        return new FeedResponse(new QueryIterable(this,
                ResourceType.Database,
                Database.class,
                Paths.DATABASES_ROOT,
                options));
    }

    /**
     * Query for databases.
     *
     * @param query   the query.
     * @param options the feed options.
     * @return the feed response with the obtained databases.
     */
    public FeedResponse queryDatabases(String query, FeedOptions options) {
        if (StringUtils.isEmpty(query)) {
            throw new IllegalArgumentException("query");
        }

        return queryDatabases(new SqlQuerySpec(query, null), options);
    }

    /**
     * Query for databases.
     *
     * @param querySpec the SQL query specification.
     * @param options   the feed options.
     * @return the feed response with the obtained databases.
     */
    public FeedResponse queryDatabases(SqlQuerySpec querySpec, FeedOptions options) {
        if (querySpec == null) {
            throw new IllegalArgumentException("querySpec");
        }

        logger.debug("Querying Databases. querySpec: [{}]", querySpec);
        return new FeedResponse(new QueryIterable(this,
                ResourceType.Database,
                Database.class,
                Paths.DATABASES_ROOT,
                querySpec,
                options));
    }

    /**
     * Creates a document collection.
     *
     * @param databaseLink the database link.
     * @param collection   the collection.
     * @param options      the request options.
     * @return the resource response with the created collection.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse createCollection(String databaseLink,
            DocumentCollection collection,
            RequestOptions options)
                    throws DocumentClientException {

        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }
        if (collection == null) {
            throw new IllegalArgumentException("collection");
        }

        logger.debug("Creating a Collection. databaseLink: [{}], Collection id: [{}]", databaseLink, collection.getId());
        DocumentClient.validateResource(collection);

        String path = Utils.joinPath(databaseLink, Paths.COLLECTIONS_PATH_SEGMENT);
        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Create,
                ResourceType.DocumentCollection,
                path,
                collection,
                requestHeaders);

        return new ResourceResponse(this.doCreate(request), DocumentCollection.class);
    }

    /**
     * Replaces a document collection.
     *
     * @param collection the document collection to use.
     * @param options    the request options.
     * @return the resource response with the replaced document collection.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse replaceCollection(DocumentCollection collection,
            RequestOptions options)
                    throws DocumentClientException {

        if (collection == null) {
            throw new IllegalArgumentException("collection");
        }

        logger.debug("Replacing a Collection. id: [{}]", collection.getId());
        DocumentClient.validateResource(collection);

        String path = Utils.joinPath(collection.getSelfLink(), null);
        Map requestHeaders = getRequestHeaders(options);

        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Replace,
                ResourceType.DocumentCollection,
                path,
                collection,
                requestHeaders);
        return new ResourceResponse(this.doReplace(request), DocumentCollection.class);
    }

    /**
     * Deletes a document collection by the collection link.
     *
     * @param collectionLink the collection link.
     * @param options        the request options.
     * @return the resource response.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse deleteCollection(String collectionLink, RequestOptions options)
            throws DocumentClientException {

        if (StringUtils.isEmpty(collectionLink)) {
            throw new IllegalArgumentException("collectionLink");
        }

        logger.debug("Deleting a Collection. collectionLink: [{}]", collectionLink);
        String path = Utils.joinPath(collectionLink, null);
        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Delete,
                ResourceType.DocumentCollection,
                path,
                requestHeaders);
        return new ResourceResponse(this.doDelete(request), DocumentCollection.class);
    }

    /**
     * Reads a document collection by the collection link.
     *
     * @param collectionLink the collection link.
     * @param options        the request options.
     * @return the resource response with the read collection.
     * @throws DocumentClientException the document client exception.
     */
    @Override
    public ResourceResponse readCollection(String collectionLink, RequestOptions options)
            throws DocumentClientException {

        if (StringUtils.isEmpty(collectionLink)) {
            throw new IllegalArgumentException("collectionLink");
        }

        logger.debug("Reading a Collection. collectionLink: [{}]", collectionLink);
        String path = Utils.joinPath(collectionLink, null);
        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Read,
                ResourceType.DocumentCollection,
                path,
                requestHeaders);

        return new ResourceResponse(this.doRead(request), DocumentCollection.class);
    }

    /**
     * Reads all document collections in a database.
     *
     * @param databaseLink the database link.
     * @param options      the fee options.
     * @return the feed response with the read collections.
     */
    public FeedResponse readCollections(String databaseLink, FeedOptions options) {

        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }

        logger.debug("Reading Collections. databaseLink: [{}]", databaseLink);
        String path = Utils.joinPath(databaseLink, Paths.COLLECTIONS_PATH_SEGMENT);
        return new FeedResponse(new QueryIterable(this,
                ResourceType.DocumentCollection,
                DocumentCollection.class,
                path,
                options));
    }

    /**
     * Query for document collections in a database.
     *
     * @param databaseLink the database link.
     * @param query        the query.
     * @param options      the feed options.
     * @return the feed response with the obtained collections.
     */
    public FeedResponse queryCollections(String databaseLink, String query, FeedOptions options) {

        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }

        if (StringUtils.isEmpty(query)) {
            throw new IllegalArgumentException("query");
        }

        return queryCollections(databaseLink, new SqlQuerySpec(query, null), options);
    }

    /**
     * Query for document collections in a database.
     *
     * @param databaseLink the database link.
     * @param querySpec    the SQL query specification.
     * @param options      the feed options.
     * @return the feed response with the obtained collections.
     */
    public FeedResponse queryCollections(String databaseLink, SqlQuerySpec querySpec,
            FeedOptions options) {

        if (StringUtils.isEmpty(databaseLink)) {
            throw new IllegalArgumentException("databaseLink");
        }

        if (querySpec == null) {
            throw new IllegalArgumentException("querySpec");
        }

        logger.debug("Querying Collections. databaseLink: [{}], querySpec [{}]", databaseLink, querySpec);
        String path = Utils.joinPath(databaseLink, Paths.COLLECTIONS_PATH_SEGMENT);
        return new FeedResponse(new QueryIterable(this,
                ResourceType.DocumentCollection,
                DocumentCollection.class,
                path,
                querySpec,
                options));
    }

    /**
     * Creates a document.
     *
     * @param collectionLink               the link to the parent document collection.
     * @param document                     the document represented as a POJO or Document object.
     * @param options                      the request options.
     * @param disableAutomaticIdGeneration the flag for disabling automatic id generation.
     * @return the resource response with the created document.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse createDocument(String collectionLink,
            Object document,
            RequestOptions options,
            boolean disableAutomaticIdGeneration)
                    throws DocumentClientException {

        logger.debug("Creating a Document. collectionLink: [{}]", collectionLink);
        final String documentCollectionLink = this.getTargetDocumentCollectionLink(collectionLink, document);
        final Object documentLocal = document;
        final RequestOptions optionsLocal = options;
        final boolean disableAutomaticIdGenerationLocal = disableAutomaticIdGeneration;
        final boolean shouldRetry = options == null || options.getPartitionKey() == null;

        RetryCreateDocumentDelegate createDelegate = new RetryCreateDocumentDelegate() {

            @Override
            public ResourceResponse apply() throws DocumentClientException {
                DocumentServiceRequest request = getCreateDocumentRequest(documentCollectionLink, documentLocal, optionsLocal,
                        disableAutomaticIdGenerationLocal, OperationType.Create);
                return new ResourceResponse(doCreate(request), Document.class);
            }
        };

        return shouldRetry
                ? RetryUtility.executeCreateDocument(createDelegate, this.collectionCache, documentCollectionLink)
                        : createDelegate.apply();
    }

    /**
     * Upserts a document.
     *
     * @param collectionLink               the link to the parent document collection.
     * @param document                     the document represented as a POJO or Document object to upsert.
     * @param options                      the request options.
     * @param disableAutomaticIdGeneration the flag for disabling automatic id generation.
     * @return the resource response with the upserted document.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse upsertDocument(String collectionLink,
            Object document,
            RequestOptions options,
            boolean disableAutomaticIdGeneration)
                    throws DocumentClientException {
        logger.debug("Upserting a Document. collectionLink: [{}]", collectionLink);
        final String documentCollectionLink = this.getTargetDocumentCollectionLink(collectionLink, document);
        final Object documentLocal = document;
        final RequestOptions optionsLocal = options;
        final boolean disableAutomaticIdGenerationLocal = disableAutomaticIdGeneration;
        final boolean shouldRetry = options == null || options.getPartitionKey() == null;

        RetryCreateDocumentDelegate upsertDelegate = new RetryCreateDocumentDelegate() {

            @Override
            public ResourceResponse apply() throws DocumentClientException {
                DocumentServiceRequest request = getCreateDocumentRequest(documentCollectionLink, documentLocal, optionsLocal,
                        disableAutomaticIdGenerationLocal, OperationType.Upsert);
                return new ResourceResponse(doUpsert(request), Document.class);
            }
        };

        return shouldRetry
                ? RetryUtility.executeCreateDocument(upsertDelegate, this.collectionCache, documentCollectionLink)
                        : upsertDelegate.apply();
    }

    @SuppressWarnings("deprecation")
    private String getTargetDocumentCollectionLink(String collectionLink, Object document) {
        if (StringUtils.isEmpty(collectionLink)) {
            throw new IllegalArgumentException("collectionLink");
        }
        if (document == null) {
            throw new IllegalArgumentException("document");
        }

        String documentCollectionLink = collectionLink;
        if (Utils.isDatabaseLink(collectionLink)) {
            // Gets the partition resolver(if it exists) for the specified database link
            PartitionResolver partitionResolver = this.getPartitionResolver(collectionLink);

            // If the partition resolver exists, get the collection to which the Create/Upsert should be directed using the partition key
            if (partitionResolver != null) {
                documentCollectionLink = partitionResolver.resolveForCreate(document);
            } else {
                throw new IllegalArgumentException(PartitionResolverErrorMessage);
            }
        }

        return documentCollectionLink;
    }

    private DocumentServiceRequest getCreateDocumentRequest(String documentCollectionLink, Object document, RequestOptions options,
            boolean disableAutomaticIdGeneration, OperationType operationType) {
        if (StringUtils.isEmpty(documentCollectionLink)) {
            throw new IllegalArgumentException("documentCollectionLink");
        }
        if (document == null) {
            throw new IllegalArgumentException("document");
        }

        Document typedDocument = Document.FromObject(document, objectMapper);

        DocumentClient.validateResource(typedDocument);

        if (typedDocument.getId() == null && !disableAutomaticIdGeneration) {
            // We are supposed to use GUID. Basically UUID is the same as GUID
            // when represented as a string.
            typedDocument.setId(Utils.getSecureRandomUUID().toString());
        }
        String path = Utils.joinPath(documentCollectionLink, Paths.DOCUMENTS_PATH_SEGMENT);
        Map requestHeaders = getRequestHeaders(options);

        DocumentServiceRequest request = DocumentServiceRequest.create(operationType,
                ResourceType.Document,
                path,
                typedDocument,
                requestHeaders);
        this.addPartitionKeyInformation(request, typedDocument, options);
        return request;
    }

    /**
     * Replaces a document using a POJO object.
     *
     * @param documentLink the document link.
     * @param document     the document represented as a POJO or Document object.
     * @param options      the request options.
     * @return the resource response with the replaced document.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse replaceDocument(String documentLink, Object document, RequestOptions options)
            throws DocumentClientException {

        if (StringUtils.isEmpty(documentLink)) {
            throw new IllegalArgumentException("documentLink");
        }

        if (document == null) {
            throw new IllegalArgumentException("document");
        }

        Document typedDocument = Document.FromObject(document, objectMapper);
        return this.replaceDocumentInternal(documentLink, typedDocument, options);
    }

    /**
     * Replaces a document with the passed in document.
     *
     * @param document the document to replace (containing the document id).
     * @param options  the request options.
     * @return the resource response with the replaced document.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse replaceDocument(Document document, RequestOptions options)
            throws DocumentClientException {

        if (document == null) {
            throw new IllegalArgumentException("document");
        }

        return this.replaceDocumentInternal(document.getSelfLink(), document, options);
    }

    private ResourceResponse replaceDocumentInternal(String documentLink, Document document, RequestOptions options)
            throws DocumentClientException {

        if (document == null) {
            throw new IllegalArgumentException("document");
        }

        logger.debug("Replacing a Document. documentLink: [{}]", documentLink);
        final String documentCollectionName = Utils.getCollectionName(documentLink);
        final String documentCollectionLink = this.getTargetDocumentCollectionLink(documentCollectionName, document);
        final String path = Utils.joinPath(documentLink, null);
        final Map requestHeaders = getRequestHeaders(options);
        final DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Replace,
                ResourceType.Document,
                path,
                document,
                requestHeaders);
        this.addPartitionKeyInformation(request, document, options);
        final boolean shouldRetry = options == null || options.getPartitionKey() == null;

        DocumentClient.validateResource(document);

        RetryCreateDocumentDelegate replaceDelegate = new RetryCreateDocumentDelegate() {

            @Override
            public ResourceResponse apply() throws DocumentClientException {
                return new ResourceResponse(doReplace(request), Document.class);
            }
        };

        return shouldRetry
                ? RetryUtility.executeCreateDocument(replaceDelegate, this.collectionCache, documentCollectionLink)
                        : replaceDelegate.apply();
    }

    /**
     * Deletes a document by the document link.
     *
     * @param documentLink the document link.
     * @param options      the request options.
     * @return the resource response.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse deleteDocument(String documentLink, RequestOptions options)
            throws DocumentClientException {

        if (StringUtils.isEmpty(documentLink)) {
            throw new IllegalArgumentException("documentLink");
        }

        logger.debug("Deleting a Document. documentLink: [{}]", documentLink);
        String path = Utils.joinPath(documentLink, null);
        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Delete, ResourceType.Document, path, requestHeaders);
        this.addPartitionKeyInformation(request, null, options);
        return new ResourceResponse(this.doDelete(request), Document.class);
    }

    /**
     * Reads a document by the document link.
     *
     * @param documentLink the document link.
     * @param options      the request options.
     * @return the resource response with the read document.
     * @throws DocumentClientException the document client exception.
     */
    public ResourceResponse readDocument(String documentLink, RequestOptions options)
            throws DocumentClientException {

        if (StringUtils.isEmpty(documentLink)) {
            throw new IllegalArgumentException("documentLink");
        }

        logger.debug("Reading a Document. documentLink: [{}]", documentLink);
        String path = Utils.joinPath(documentLink, null);
        Map requestHeaders = getRequestHeaders(options);
        DocumentServiceRequest request = DocumentServiceRequest.create(OperationType.Read, ResourceType.Document, path, requestHeaders);
        this.addPartitionKeyInformation(request, null, options);
        return new ResourceResponse(this.doRead(request), Document.class);
    }

    /**
     * Reads all documents in a document collection.
     *
     * @param collectionLink the collection link.
     * @param options        the feed options.
     * @return the feed response with read documents.
     */
    public FeedResponse readDocuments(String collectionLink, FeedOptions options) {

        if (StringUtils.isEmpty(collectionLink)) {
            throw new IllegalArgumentException("collectionLink");
        }

        logger.debug("Reading Documents. collectionLink: [{}]", collectionLink);
        String path = Utils.joinPath(collectionLink, Paths.DOCUMENTS_PATH_SEGMENT);
        return new FeedResponse(new QueryIterable(this,
                ResourceType.Document,
                Document.class,
                path,
                options));
    }

    /**
     * Query for documents in a document collection.
     *
     * @param collectionLink the link to the parent document collection.
     * @param query          the query.
     * @param options        the feed options.
     * @return the feed response with the obtained documents.
     */
    public FeedResponse queryDocuments(String collectionLink, String query, FeedOptions options) {
        return this.queryDocuments(collectionLink, query, options, null);
    }

    /**
     * Query for documents in a document collection with a partitionKey
     *
     * @param collectionLink the link to the parent document collection.
     * @param query          the query.
     * @param options        the feed options.
     * @param partitionKey   the partitionKey.
     * @return the feed response with the obtained documents.
     */
    public FeedResponse queryDocuments(String collectionLink, String query, FeedOptions options,
            Object partitionKey) {
        if (StringUtils.isEmpty(collectionLink)) {
            throw new IllegalArgumentException("collectionLink");
        }
        if (StringUtils.isEmpty(query)) {
            throw new IllegalArgumentException("query");
        }

        return queryDocuments(collectionLink, new SqlQuerySpec(query, null), options, partitionKey);
    }

    /**
     * Query for documents in a document collection.
     *
     * @param collectionLink the link to the parent document collection.
     * @param querySpec      the SQL query specification.
     * @param options        the feed options.
     * @return the feed response with the obtained documents.
     */
    public FeedResponse queryDocuments(String collectionLink, SqlQuerySpec querySpec, FeedOptions options) {
        return this.queryDocuments(collectionLink, querySpec, options, null);
    }

    /**
     * Query for documents in a document collection.
     *
     * @param collectionLink the link to the parent document collection.
     * @param querySpec      the SQL query specification.
     * @param options        the feed options.
     * @param partitionKey   the partitionKey.
     * @return the feed response with the obtained documents.
     */
    public FeedResponse queryDocuments(String collectionLink, SqlQuerySpec querySpec, FeedOptions options,
            Object partitionKey) {
        if (StringUtils.isEmpty(collectionLink)) {
            throw new IllegalArgumentException("collectionLink");
        }
        if (querySpec == null) {
            throw new IllegalArgumentException("querySpec");
        }

        logger.debug("Querying Documents. collectionLink: [{}], querySpec [{}]", collectionLink, querySpec);
        String path;
        if (Utils.isDatabaseLink(collectionLink)) {
            path = collectionLink;
        } else {
            path = Utils.joinPath(collectionLink, Paths.DOCUMENTS_PATH_SEGMENT);
        }

        return new FeedResponse(new QueryIterable(this,
                ResourceType.Document,
                Document.class,
                path,
                querySpec,
                options,
                partitionKey));
    }


    /**
     * Query for aggregation values in a document collection.
     *
     * @param collectionLink the link to the parent document collection.
     * @param query          the query string.
     * @param feedOptions    the feed options.
     * @return               a list containing the aggregation values
     */
    public List