Subpartitioning: Adds SDK changes to support subpartitioning.

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/HttpConstants.java

@@ -273,7 +273,7 @@ public static class A_IMHeaderValues {
     }
 
     public static class Versions {
-        public static final String CURRENT_VERSION = "2018-12-31";
+        public static final String CURRENT_VERSION = "2020-07-15";
         public static final String QUERY_VERSION = "1.0";
         public static final String AZURE_COSMOS_PROPERTIES_FILE_NAME = "azure-cosmos.properties";
 

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/RxDocumentClientImpl.java

@@ -1310,20 +1310,35 @@ public static PartitionKeyInternal extractPartitionKeyValueFromDocument(
             InternalObjectNode document,
             PartitionKeyDefinition partitionKeyDefinition) {
         if (partitionKeyDefinition != null) {
-            String path = partitionKeyDefinition.getPaths().iterator().next();
-            List<String> parts = PathParser.getPathParts(path);
-            if (parts.size() >= 1) {
-                Object value = ModelBridgeInternal.getObjectByPathFromJsonSerializable(document, parts);
-                if (value == null || value.getClass() == ObjectNode.class) {
-                    value = ModelBridgeInternal.getNonePartitionKey(partitionKeyDefinition);
-                }
+            switch (partitionKeyDefinition.getKind()) {
+                case HASH:
+                    String path = partitionKeyDefinition.getPaths().iterator().next();
+                    List<String> parts = PathParser.getPathParts(path);
+                    if (parts.size() >= 1) {
+                        Object value = ModelBridgeInternal.getObjectByPathFromJsonSerializable(document, parts);
+                        if (value == null || value.getClass() == ObjectNode.class) {
+                            value = ModelBridgeInternal.getNonePartitionKey(partitionKeyDefinition);
+                        }
 
-                if (value instanceof PartitionKeyInternal) {
-                    return (PartitionKeyInternal) value;
-                } else {
-                    return PartitionKeyInternal.fromObjectArray(Collections.singletonList(value), false);
+                        if (value instanceof PartitionKeyInternal) {
+                            return (PartitionKeyInternal) value;
+                        } else {
+                            return PartitionKeyInternal.fromObjectArray(Collections.singletonList(value), false);
+                        }
+                    }
+                    break;
+                case MULTI_HASH:
+                    Object[] partitionKeyValues = new Object[partitionKeyDefinition.getPaths().size()];
+                    for(int pathIter = 0 ; pathIter < partitionKeyDefinition.getPaths().size(); pathIter++){
+                        String partitionPath = partitionKeyDefinition.getPaths().get(pathIter);
+                        List<String> partitionPathParts = PathParser.getPathParts(partitionPath);
+                        partitionKeyValues[pathIter] = ModelBridgeInternal.getObjectByPathFromJsonSerializable(document, partitionPathParts);
+                    }
+                    return PartitionKeyInternal.fromObjectArray(partitionKeyValues, false);
+
+                default:
+                    throw new IllegalArgumentException("Unrecognized Partition kind: " + partitionKeyDefinition.getKind());
                 }
-            }
         }
 
         return null;

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/routing/PartitionKeyInternalHelper.java

@@ -35,6 +35,8 @@ public class PartitionKeyInternalHelper {
         (byte) 0x3F, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF,
         (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF, (byte) 0xFF});
 
+    private static final int HASH_V2_EPK_LENGTH = 32;
+
     static byte[] uIntToBytes(UInt128 unit) {
         ByteBuffer buffer = ByteBuffer.allocate(Long.BYTES * 2);
         buffer.putLong(unit.low);
@@ -92,6 +94,31 @@ static public String getEffectivePartitionKeyForHashPartitioningV2(PartitionKeyI
         }
     }
 
+    static String getEffectivePartitionKeyForMultiHashPartitioning(PartitionKeyInternal partitionKeyInternal) {
+        StringBuilder stringBuilder = new StringBuilder(partitionKeyInternal.components.size() * HASH_V2_EPK_LENGTH);
+        for (int i = 0; i < partitionKeyInternal.components.size(); i++) {
+            try(ByteBufferOutputStream byteArrayBuffer = new ByteBufferOutputStream())  {
+                partitionKeyInternal.components.get(i).writeForHashingV2(byteArrayBuffer);
+
+                ByteBuffer byteBuffer = byteArrayBuffer.asByteBuffer();
+                UInt128 hashAsUnit128 = MurmurHash3_128.hash128(byteBuffer.array(), byteBuffer.limit());
+
+                byte[] hash = uIntToBytes(hashAsUnit128);
+                Bytes.reverse(hash);
+
+                // Reset 2 most significant bits, as max exclusive value is 'FF'.
+                // Plus one more just in case.
+                hash[0] &= 0x3F;
+
+                stringBuilder.append(HexConvert.bytesToHex(hash));
+            } catch (IOException e) {
+                throw new IllegalArgumentException(e);
+            }
+        }
+
+        return stringBuilder.toString();
+    }
+
     static String getEffectivePartitionKeyForHashPartitioning(PartitionKeyInternal partitionKeyInternal) {
         IPartitionKeyComponent[] truncatedComponents = new IPartitionKeyComponent[partitionKeyInternal.components.size()];
 
@@ -138,7 +165,7 @@ public static String getEffectivePartitionKeyString(PartitionKeyInternal partiti
             return MaximumExclusiveEffectivePartitionKey;
         }
 
-        if (partitionKeyInternal.components.size() < partitionKeyDefinition.getPaths().size()) {
+        if (partitionKeyInternal.components.size() < partitionKeyDefinition.getPaths().size() && partitionKeyDefinition.getKind() != PartitionKind.MULTI_HASH) {
             throw new IllegalArgumentException(RMResources.TooFewPartitionKeyComponents);
         }
 
@@ -161,6 +188,9 @@ public static String getEffectivePartitionKeyString(PartitionKeyInternal partiti
                     return getEffectivePartitionKeyForHashPartitioning(partitionKeyInternal);
                 }
 
+            case MULTI_HASH:
+                return getEffectivePartitionKeyForMultiHashPartitioning(partitionKeyInternal);
+
             default:
                 return toHexEncodedBinaryString(partitionKeyInternal.components);
         }

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/PartitionKeyBuilder.java

@@ -0,0 +1,118 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.cosmos.models;
+
+import com.azure.cosmos.implementation.Undefined;
+import com.azure.cosmos.implementation.routing.PartitionKeyInternal;
+import com.azure.cosmos.util.Beta;
+import com.azure.cosmos.util.Beta.SinceVersion;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+public final class PartitionKeyBuilder {
+    private final List<Object> partitionKeyValues;
+
+    /**
+     * Constructor. CREATE a new instance of the PartitionKeyBuilder object.
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    public PartitionKeyBuilder() {
+        this.partitionKeyValues = new ArrayList<Object>();
+    }
+
+    /**
+     * Adds partition value of type string
+     * @param value The value of type string to be used as partition key
+     * @return The current PartitionKeyBuilder object
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    public PartitionKeyBuilder add(String value) {
+        this.partitionKeyValues.add(value);
+        return this;
+    }
+
+    /**
+     * Adds partition value of type double
+     * @param value The value of type double to be used as partition key
+     * @return The current PartitionKeyBuilder object
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    public PartitionKeyBuilder add(double value) {
+        this.partitionKeyValues.add(value);
+        return this;
+    }
+
+    /**
+     * Adds partition value of type boolean
+     * @param value The value of type boolean to be used as partition key
+     * @return The current PartitionKeyBuilder object
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    public PartitionKeyBuilder add(boolean value) {
+        this.partitionKeyValues.add(value);
+        return this;
+    }
+
+    /**
+     * Adds a null partition key value
+     * @return The current PartitionKeyBuilder object
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    public PartitionKeyBuilder addNullValue() {
+        this.partitionKeyValues.add(null);
+        return this;
+    }
+
+    /**
+     * Adds a None Partition Key
+     * @return The current PartitionKeyBuilder object
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    public PartitionKeyBuilder addNoneValue() {
+        this.partitionKeyValues.add(PartitionKey.NONE);
+        return this;
+    }
+
+    /**
+     * Builds a new instance of the type PartitionKey with the specified Partition Key values.
+     * @return PartitionKey object
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    public PartitionKey build() {
+        // Why these checks?
+        // These changes are being added for SDK to support multiple paths in a partition key.
+        //
+        // Currently, when a resource does not specify a value for the PartitionKey,
+        // we assign a temporary value `PartitionKey.None` and later discern whether
+        // it is a PartitionKey.Undefined or PartitionKey.Empty based on the Collection Type.
+        // We retain this behaviour for single path partition keys.
+        //
+        // For collections with multiple path keys, absence of a partition key values is
+        // always treated as a PartitionKey.Undefined.
+        if(this.partitionKeyValues.size() == 0) {
+            throw new IllegalArgumentException("No partition key value has been specified");
+        }
+
+        if(this.partitionKeyValues.size() == 1 && PartitionKey.NONE.equals(this.partitionKeyValues.get(0))) {
+            return PartitionKey.NONE;
+        }
+
+        PartitionKeyInternal partitionKeyInternal;
+        Object[] valueArray = new Object[this.partitionKeyValues.size()];
+        for(int i = 0; i < this.partitionKeyValues.size(); i++) {
+            Object val = this.partitionKeyValues.get(i);
+            if(PartitionKey.NONE.equals(val)) {
+                valueArray[i] = Undefined.value();
+            }
+            else {
+                valueArray[i] = val;
+            }
+        }
+
+        partitionKeyInternal = PartitionKeyInternal.fromObjectArray(valueArray, true);
+        return new PartitionKey(partitionKeyInternal);
+    }
+}

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/PartitionKind.java

@@ -3,14 +3,24 @@
 
 package com.azure.cosmos.models;
 
+import com.azure.cosmos.util.Beta;
+import com.azure.cosmos.util.Beta.SinceVersion;
+
 /**
  * Specifies the partition scheme for an multiple-partitioned container in the Azure Cosmos DB database service.
  */
 public enum PartitionKind {
     /**
      * The Partition of a item is calculated based on the hash value of the PartitionKey.
      */
-    HASH("Hash");
+    HASH("Hash"),
+
+    RANGE("Range"),
+    /**
+     * The Partition of a item is calculated based on the hash value of multiple PartitionKeys.
+     */
+    @Beta(value = SinceVersion.V4_16_0, warningText = Beta.PREVIEW_SUBJECT_TO_CHANGE_WARNING)
+    MULTI_HASH("MultiHash");
 
     PartitionKind(String overWireValue) {
         this.overWireValue = overWireValue;

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/util/Beta.java

@@ -10,13 +10,14 @@
 import java.lang.annotation.Target;
 
 import static java.lang.annotation.ElementType.CONSTRUCTOR;
+import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.ElementType.TYPE;
 
 @Documented
 @Retention(RetentionPolicy.CLASS)
-@Target({ TYPE, METHOD, PARAMETER, CONSTRUCTOR })
+@Target({ TYPE, METHOD, PARAMETER, CONSTRUCTOR, FIELD })
 @Inherited
 /**
  * Indicates functionality that is in preview and as such is subject to change in non-backwards compatible ways in future releases,

sdk/cosmos/azure-cosmos/src/test/java/com/azure/cosmos/CosmosContainerTest.java

@@ -27,6 +27,8 @@
 import com.azure.cosmos.models.IndexingPolicy;
 import com.azure.cosmos.models.PartitionKey;
 import com.azure.cosmos.models.PartitionKeyDefinition;
+import com.azure.cosmos.models.PartitionKeyDefinitionVersion;
+import com.azure.cosmos.models.PartitionKind;
 import com.azure.cosmos.models.SqlQuerySpec;
 import com.azure.cosmos.models.ThroughputProperties;
 import com.azure.cosmos.rx.TestSuiteBase;
@@ -47,6 +49,7 @@
 import java.util.Base64;
 import java.util.List;
 import java.util.UUID;
+import java.util.ArrayList;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.fail;
@@ -764,6 +767,40 @@ public void readAllContainers() throws Exception{
         assertThat(feedResponseIterator1.iterator().hasNext()).isTrue();
     }
 
+    @Test(groups = { "emulator" }, timeOut = TIMEOUT)
+    public void crudMultiHashContainer() throws Exception {
+        String collectionName = UUID.randomUUID().toString();
+
+        PartitionKeyDefinition partitionKeyDefinition = new PartitionKeyDefinition();
+        partitionKeyDefinition.setKind(PartitionKind.MULTI_HASH);
+        partitionKeyDefinition.setVersion(PartitionKeyDefinitionVersion.V2);
+        ArrayList<String> paths = new ArrayList<>();
+        paths.add("/city");
+        paths.add("/zipcode");
+        partitionKeyDefinition.setPaths(paths);
+
+        CosmosContainerProperties containerProperties = getCollectionDefinition(collectionName, partitionKeyDefinition);
+
+        //MultiHash collection create
+        CosmosContainerResponse containerResponse = createdDatabase.createContainer(containerProperties);
+        validateContainerResponse(containerProperties, containerResponse);
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getKind() == PartitionKind.MULTI_HASH);
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getPaths().size() == paths.size());
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getPaths().get(0) == paths.get(0));
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getPaths().get(1) == paths.get(1));
+
+        //MultiHash collection read
+        CosmosContainer multiHashContainer = createdDatabase.getContainer(collectionName);
+        containerResponse = multiHashContainer.read();
+        validateContainerResponse(containerProperties, containerResponse);
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getKind() == PartitionKind.MULTI_HASH);
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getPaths().size() == paths.size());
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getPaths().get(0) == paths.get(0));
+        assertThat(containerResponse.getProperties().getPartitionKeyDefinition().getPaths().get(1) == paths.get(1));
+
+        //MultiHash collection delete
+        CosmosContainerResponse deleteResponse = multiHashContainer.delete();
+    }
 
     @Test(groups = { "emulator" }, timeOut = TIMEOUT)
     public void queryContainer() throws Exception{