Implement UUID representation specification

JAVA-3516

Author: jyemin

bson/src/main/org/bson/UuidRepresentation.java

@@ -24,6 +24,14 @@
  * @since 3.0
  */
 public enum UuidRepresentation {
+
+    /**
+     * An unspecified representation of UUID.  Essentially, this is the null representation value.
+     *
+     * @since 3.12
+     */
+    UNSPECIFIED,
+
     /**
      * The canonical representation of UUID
      *

bson/src/main/org/bson/codecs/DocumentCodec.java

@@ -16,7 +16,6 @@
 
 package org.bson.codecs;
 
-import org.bson.BsonBinarySubType;
 import org.bson.BsonDocument;
 import org.bson.BsonDocumentWriter;
 import org.bson.BsonReader;
@@ -25,6 +24,7 @@
 import org.bson.BsonWriter;
 import org.bson.Document;
 import org.bson.Transformer;
+import org.bson.UuidRepresentation;
 import org.bson.codecs.configuration.CodecRegistry;
 
 import java.util.ArrayList;
@@ -42,7 +42,7 @@
  * @see org.bson.Document
  * @since 3.0
  */
-public class DocumentCodec implements CollectibleCodec<Document> {
+public class DocumentCodec implements CollectibleCodec<Document>, OverridableUuidRepresentationCodec<Document> {
 
     private static final String ID_FIELD_NAME = "_id";
     private static final CodecRegistry DEFAULT_REGISTRY = fromProviders(asList(new ValueCodecProvider(),
@@ -54,6 +54,7 @@ public class DocumentCodec implements CollectibleCodec<Document> {
     private final CodecRegistry registry;
     private final IdGenerator idGenerator;
     private final Transformer valueTransformer;
+    private final UuidRepresentation uuidRepresentation;
 
     /**
      * Construct a new instance with a default {@code CodecRegistry}.
@@ -92,15 +93,27 @@ public DocumentCodec(final CodecRegistry registry, final BsonTypeClassMap bsonTy
      * @param valueTransformer the value transformer to use as a final step when decoding the value of any field in the document
      */
     public DocumentCodec(final CodecRegistry registry, final BsonTypeClassMap bsonTypeClassMap, final Transformer valueTransformer) {
+        this(registry, new BsonTypeCodecMap(notNull("bsonTypeClassMap", bsonTypeClassMap), registry),
+                new ObjectIdGenerator(), valueTransformer, UuidRepresentation.JAVA_LEGACY);
+    }
+
+    private DocumentCodec(final CodecRegistry registry, final BsonTypeCodecMap bsonTypeCodecMap, final IdGenerator idGenerator,
+                          final Transformer valueTransformer, final UuidRepresentation uuidRepresentation) {
         this.registry = notNull("registry", registry);
-        this.bsonTypeCodecMap = new BsonTypeCodecMap(notNull("bsonTypeClassMap", bsonTypeClassMap), registry);
-        this.idGenerator = new ObjectIdGenerator();
+        this.bsonTypeCodecMap = bsonTypeCodecMap;
+        this.idGenerator = idGenerator;
         this.valueTransformer = valueTransformer != null ? valueTransformer : new Transformer() {
             @Override
             public Object transform(final Object value) {
                 return value;
             }
         };
+        this.uuidRepresentation = uuidRepresentation;
+    }
+
+    @Override
+    public Codec<Document> withUuidRepresentation(final UuidRepresentation uuidRepresentation) {
+        return new DocumentCodec(registry, bsonTypeCodecMap, idGenerator, valueTransformer, uuidRepresentation);
     }
 
     @Override
@@ -216,10 +229,29 @@ private Object readValue(final BsonReader reader, final DecoderContext decoderCo
             return null;
         } else if (bsonType == BsonType.ARRAY) {
             return readList(reader, decoderContext);
-        } else if (bsonType == BsonType.BINARY && BsonBinarySubType.isUuid(reader.peekBinarySubType()) && reader.peekBinarySize() == 16) {
-            return registry.get(UUID.class).decode(reader, decoderContext);
+        } else {
+            Codec<?> codec = bsonTypeCodecMap.get(bsonType);
+
+            if (bsonType == BsonType.BINARY && reader.peekBinarySize() == 16) {
+                switch (reader.peekBinarySubType()) {
+                    case 3:
+                        if (uuidRepresentation == UuidRepresentation.JAVA_LEGACY
+                                || uuidRepresentation == UuidRepresentation.C_SHARP_LEGACY
+                                || uuidRepresentation == UuidRepresentation.PYTHON_LEGACY) {
+                            codec = registry.get(UUID.class);
+                        }
+                        break;
+                    case 4:
+                        if (uuidRepresentation == UuidRepresentation.JAVA_LEGACY || uuidRepresentation == UuidRepresentation.STANDARD) {
+                            codec = registry.get(UUID.class);
+                        }
+                        break;
+                    default:
+                        break;
+                }
+            }
+            return valueTransformer.transform(codec.decode(reader, decoderContext));
         }
-        return valueTransformer.transform(bsonTypeCodecMap.get(bsonType).decode(reader, decoderContext));
     }
 
     private List<Object> readList(final BsonReader reader, final DecoderContext decoderContext) {

bson/src/main/org/bson/codecs/OverridableUuidRepresentationCodec.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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 org.bson.codecs;
+
+import org.bson.UuidRepresentation;
+
+/**
+ * A marker interface for {@code Codec} implementations that can derive a new instance that overrides the {@code UuidRepresentation}.
+ * @param <T> the value type
+ * @since 3.12
+ */
+public interface OverridableUuidRepresentationCodec<T> {
+    /**
+     * Implementations must return a new instance with the {@code UuidRepresentation} overridden with the given value.
+     *
+     * @param uuidRepresentation the UuidRepresentation
+     * @return a new instance equivalent to this but with the given UuidRepresentation
+     */
+    Codec<T> withUuidRepresentation(UuidRepresentation uuidRepresentation);
+}

bson/src/main/org/bson/codecs/OverridableUuidRepresentationUuidCodec.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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 org.bson.codecs;
+
+import org.bson.UuidRepresentation;
+
+import java.util.UUID;
+
+/**
+ * An extension of {@code UuidCodec} that allows its configured {@code UuidRepresentation} to be overridden by an externally configured
+ * {@code UuidRepresentation}, most likely configured on {@code MongoClientSettings} or {@code MongoClientOptions}.
+ *
+ * @since 3.12
+ */
+public class OverridableUuidRepresentationUuidCodec extends UuidCodec implements OverridableUuidRepresentationCodec<UUID> {
+
+    /**
+     * Construct an instance with the default UUID representation.
+     */
+    public OverridableUuidRepresentationUuidCodec() {
+    }
+
+    /**
+     * Construct an instance with the given UUID representation.
+     *
+     * @param uuidRepresentation the UUID representation
+     */
+    public OverridableUuidRepresentationUuidCodec(final UuidRepresentation uuidRepresentation) {
+        super(uuidRepresentation);
+    }
+
+    @Override
+    public Codec<UUID> withUuidRepresentation(final UuidRepresentation uuidRepresentation) {
+        return new OverridableUuidRepresentationUuidCodec(uuidRepresentation);
+    }
+}

bson/src/main/org/bson/codecs/UuidCodec.java

@@ -22,20 +22,21 @@
 import org.bson.BsonReader;
 import org.bson.BsonWriter;
 import org.bson.UuidRepresentation;
-
+import org.bson.codecs.configuration.CodecConfigurationException;
 import org.bson.internal.UuidHelper;
 
 import java.util.UUID;
 
+import static org.bson.assertions.Assertions.notNull;
+
 /**
  * Encodes and decodes {@code UUID} objects.
  *
  * @since 3.0
  */
 public class UuidCodec implements Codec<UUID> {
 
-    private final UuidRepresentation encoderUuidRepresentation;
-    private final UuidRepresentation decoderUuidRepresentation;
+    private final UuidRepresentation uuidRepresentation;
 
     /**
      * The default UUIDRepresentation is JAVA_LEGACY to be compatible with existing documents
@@ -44,23 +45,35 @@ public class UuidCodec implements Codec<UUID> {
      * @see org.bson.UuidRepresentation
      */
     public UuidCodec(final UuidRepresentation uuidRepresentation) {
-        this.encoderUuidRepresentation = uuidRepresentation;
-        this.decoderUuidRepresentation = uuidRepresentation;
+        notNull("uuidRepresentation", uuidRepresentation);
+        this.uuidRepresentation = uuidRepresentation;
     }
 
     /**
      * The constructor for UUIDCodec, default is JAVA_LEGACY
      */
     public UuidCodec() {
-        this.encoderUuidRepresentation = UuidRepresentation.JAVA_LEGACY;
-        this.decoderUuidRepresentation = UuidRepresentation.JAVA_LEGACY;
+        this.uuidRepresentation = UuidRepresentation.JAVA_LEGACY;
+    }
+
+    /**
+     * The {@code UuidRepresentation} with which this instance is configured
+     *
+     * @return the uuid representation
+     * @since 3.12
+     */
+    public UuidRepresentation getUuidRepresentation() {
+        return uuidRepresentation;
     }
 
     @Override
     public void encode(final BsonWriter writer, final UUID value, final EncoderContext encoderContext) {
-        byte[] binaryData = UuidHelper.encodeUuidToBinary(value, encoderUuidRepresentation);
+        if (uuidRepresentation == UuidRepresentation.UNSPECIFIED) {
+            throw new CodecConfigurationException("The uuidRepresentation has not been specified, so the UUID cannot be encoded.");
+        }
+        byte[] binaryData = UuidHelper.encodeUuidToBinary(value, uuidRepresentation);
         // changed the default subtype to STANDARD since 3.0
-        if (encoderUuidRepresentation == UuidRepresentation.STANDARD) {
+        if (uuidRepresentation == UuidRepresentation.STANDARD) {
             writer.writeBinaryData(new BsonBinary(BsonBinarySubType.UUID_STANDARD, binaryData));
         } else {
             writer.writeBinaryData(new BsonBinary(BsonBinarySubType.UUID_LEGACY, binaryData));
@@ -77,11 +90,18 @@ public UUID decode(final BsonReader reader, final DecoderContext decoderContext)
 
         byte[] bytes = reader.readBinaryData().getData();
 
-        return UuidHelper.decodeBinaryToUuid(bytes, subType, decoderUuidRepresentation);
+        return UuidHelper.decodeBinaryToUuid(bytes, subType, uuidRepresentation);
     }
 
     @Override
     public Class<UUID> getEncoderClass() {
         return UUID.class;
     }
+
+    @Override
+    public String toString() {
+        return "UuidCodec{"
+                + "uuidRepresentation=" + uuidRepresentation
+                + '}';
+    }
 }

bson/src/main/org/bson/codecs/ValueCodecProvider.java

@@ -85,7 +85,7 @@ private void addCodecs() {
         addCodec(new CharacterCodec());
         addCodec(new StringCodec());
         addCodec(new SymbolCodec());
-        addCodec(new UuidCodec());
+        addCodec(new OverridableUuidRepresentationUuidCodec());
 
         addCodec(new ByteCodec());
         addCodec(new PatternCodec());

bson/src/main/org/bson/codecs/configuration/CodecRegistries.java

@@ -17,6 +17,7 @@
 package org.bson.codecs.configuration;
 
 import org.bson.codecs.Codec;
+import org.bson.internal.ProvidersCodecRegistry;
 
 import java.util.ArrayList;
 import java.util.List;

bson/src/main/org/bson/codecs/configuration/ChildCodecRegistry.java renamed to bson/src/main/org/bson/internal/ChildCodecRegistry.java

@@ -14,19 +14,20 @@
  * limitations under the License.
  */
 
-package org.bson.codecs.configuration;
+package org.bson.internal;
 
 
 import org.bson.codecs.Codec;
+import org.bson.codecs.configuration.CodecRegistry;
 
 // An implementation of CodecRegistry that is used to detect cyclic dependencies between Codecs
 class ChildCodecRegistry<T> implements CodecRegistry {
 
     private final ChildCodecRegistry<?> parent;
-    private final ProvidersCodecRegistry registry;
+    private final CycleDetectingCodecRegistry registry;
     private final Class<T> codecClass;
 
-    ChildCodecRegistry(final ProvidersCodecRegistry registry, final Class<T> codecClass) {
+    ChildCodecRegistry(final CycleDetectingCodecRegistry registry, final Class<T> codecClass) {
         this.codecClass = codecClass;
         this.parent = null;
         this.registry = registry;

bson/src/main/org/bson/codecs/configuration/CodecCache.java renamed to bson/src/main/org/bson/internal/CodecCache.java

@@ -14,9 +14,10 @@
  * limitations under the License.
  */
 
-package org.bson.codecs.configuration;
+package org.bson.internal;
 
 import org.bson.codecs.Codec;
+import org.bson.codecs.configuration.CodecConfigurationException;
 
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;

bson/src/main/org/bson/internal/CodecRegistryHelper.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2008-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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 org.bson.internal;
+
+import org.bson.UuidRepresentation;
+import org.bson.codecs.configuration.CodecConfigurationException;
+import org.bson.codecs.configuration.CodecProvider;
+import org.bson.codecs.configuration.CodecRegistry;
+
+public final class CodecRegistryHelper {
+
+    public static CodecRegistry createRegistry(final CodecRegistry codecRegistry, final UuidRepresentation uuidRepresentation) {
+        CodecRegistry retVal = codecRegistry;
+        if (uuidRepresentation != UuidRepresentation.JAVA_LEGACY) {
+            if (codecRegistry instanceof CodecProvider) {
+                retVal = new OverridableUuidRepresentationCodecRegistry((CodecProvider) codecRegistry, uuidRepresentation);
+            } else {
+                throw new CodecConfigurationException("Changing the default UuidRepresentation requires a CodecRegistry that also "
+                        +    "implements the CodecProvider interface");
+            }
+        }
+        return retVal;
+    }
+
+    private CodecRegistryHelper() {
+    }
+}