Merge branch '260-support-new-external-id-types-like-uuidv4' into 'dev'

greenrobot-team · greenrobot-team · commit 80bc419a3146 · 2025-03-12T06:20:41.000Z
Support new UUID external ID types #260 See merge request objectbox/objectbox-java!155
diff --git a/objectbox-java-api/src/main/java/io/objectbox/annotation/ExternalPropertyType.java b/objectbox-java-api/src/main/java/io/objectbox/annotation/ExternalPropertyType.java
@@ -31,6 +31,12 @@ public enum ExternalPropertyType {
      */
     INT_128,
     /**
+     * A UUID (Universally Unique Identifier) as defined by RFC 9562.
+     * <p>
+     * ObjectBox uses the UUIDv7 scheme (timestamp + random) to create new UUIDs. UUIDv7 is a good choice for database
+     * keys as it's mostly sequential and encodes a timestamp. However, if keys are used externally, consider
+     * {@link #UUID_V4} for better privacy by not exposing any time information.
+     * <p>
      * Representing type: ByteVector
      * <p>
      * Encoding: 1:1 binary representation (16 bytes)
@@ -44,6 +50,32 @@ public enum ExternalPropertyType {
      * Encoding: 1:1 binary representation (16 bytes)
      */
     DECIMAL_128,
+    /**
+     * UUID represented as a string of 36 characters, e.g. "019571b4-80e3-7516-a5c1-5f1053d23fff".
+     * <p>
+     * For efficient storage, consider the {@link #UUID} type instead, which occupies only 16 bytes (20 bytes less).
+     * This type may still be a convenient alternative as the string type is widely supported and more human-readable.
+     * In accordance to standards, new UUIDs generated by ObjectBox use lowercase hexadecimal digits.
+     * <p>
+     * Representing type: String
+     */
+    UUID_STRING,
+    /**
+     * A UUID (Universally Unique Identifier) as defined by RFC 9562.
+     * <p>
+     * ObjectBox uses the UUIDv4 scheme (completely random) to create new UUIDs.
+     * <p>
+     * Representing type: ByteVector
+     * <p>
+     * Encoding: 1:1 binary representation (16 bytes)
+     */
+    UUID_V4,
+    /**
+     * Like {@link #UUID_STRING}, but using the UUIDv4 scheme (completely random) to create new UUID.
+     * <p>
+     * Representing type: String
+     */
+    UUID_V4_STRING,
     /**
      * A key/value map; e.g. corresponds to a JSON object or a MongoDB document (although not keeping the key order).
      * Unlike the Flex type, this must contain a map value (e.g. not a vector or a scalar).
diff --git a/objectbox-java/src/main/java/io/objectbox/model/ExternalPropertyType.java b/objectbox-java/src/main/java/io/objectbox/model/ExternalPropertyType.java
@@ -37,6 +37,10 @@ private ExternalPropertyType() { }
   public static final short Int128 = 100;
   public static final short Reserved1 = 101;
   /**
+   * A UUID (Universally Unique Identifier) as defined by RFC 9562.
+   * ObjectBox uses the UUIDv7 scheme (timestamp + random) to create new UUIDs.
+   * UUIDv7 is a good choice for database keys as it's mostly sequential and encodes a timestamp.
+   * However, if keys are used externally, consider UuidV4 for better privacy by not exposing any time information.
    * Representing type: ByteVector
    * Encoding: 1:1 binary representation (16 bytes)
    */
@@ -47,9 +51,26 @@ private ExternalPropertyType() { }
    * Encoding: 1:1 binary representation (16 bytes)
    */
   public static final short Decimal128 = 103;
-  public static final short Reserved2 = 104;
-  public static final short Reserved3 = 105;
-  public static final short Reserved4 = 106;
+  /**
+   * UUID represented as a string of 36 characters, e.g. "019571b4-80e3-7516-a5c1-5f1053d23fff".
+   * For efficient storage, consider the Uuid type instead, which occupies only 16 bytes (20 bytes less).
+   * This type may still be a convenient alternative as the string type is widely supported and more human-readable.
+   * In accordance to standards, new UUIDs generated by ObjectBox use lowercase hexadecimal digits.
+   * Representing type: String
+   */
+  public static final short UuidString = 104;
+  /**
+   * A UUID (Universally Unique Identifier) as defined by RFC 9562.
+   * ObjectBox uses the UUIDv4 scheme (completely random) to create new UUIDs.
+   * Representing type: ByteVector
+   * Encoding: 1:1 binary representation (16 bytes)
+   */
+  public static final short UuidV4 = 105;
+  /**
+   * Like UuidString, but using the UUIDv4 scheme (completely random) to create new UUID.
+   * Representing type: String
+   */
+  public static final short UuidV4String = 106;
   /**
    * A key/value map; e.g. corresponds to a JSON object or a MongoDB document (although not keeping the key order).
    * Unlike the Flex type, this must contain a map value (e.g. not a vector or a scalar).
@@ -123,7 +144,7 @@ private ExternalPropertyType() { }
    */
   public static final short MongoRegex = 127;
 
-  public static final String[] names = { "Unknown", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "Int128", "Reserved1", "Uuid", "Decimal128", "Reserved2", "Reserved3", "Reserved4", "FlexMap", "FlexVector", "Json", "Bson", "JavaScript", "Reserved5", "Reserved6", "Reserved7", "Reserved8", "Int128Vector", "Reserved9", "UuidVector", "Reserved10", "Reserved11", "Reserved12", "Reserved13", "MongoId", "MongoIdVector", "MongoTimestamp", "MongoBinary", "MongoRegex", };
+  public static final String[] names = { "Unknown", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "", "Int128", "Reserved1", "Uuid", "Decimal128", "UuidString", "UuidV4", "UuidV4String", "FlexMap", "FlexVector", "Json", "Bson", "JavaScript", "Reserved5", "Reserved6", "Reserved7", "Reserved8", "Int128Vector", "Reserved9", "UuidVector", "Reserved10", "Reserved11", "Reserved12", "Reserved13", "MongoId", "MongoIdVector", "MongoTimestamp", "MongoBinary", "MongoRegex", };
 
   public static String name(int e) { return names[e]; }
 }
