Update release notes, javadocs, version references

Author: cowtowncoder

README.md

@@ -67,7 +67,7 @@ UUID uuid = Generators.nameBasedgenerator().generate("string to hash"); // Versi
 // With JUG 4.1+: support for https://github.com/uuid6/uuid6-ietf-draft versions 6 and 7:
 UUID uuid = Generators.timeBasedReorderedGenerator().generate(); // Version 6
 UUID uuid = Generators.timeBasedEpochGenerator().generate(); // Version 7
-UUID uuid = Generators.timeBasedEpochRandomGenerator().generate(); // Version 7 with random values
+UUID uuid = Generators.timeBasedEpochRandomGenerator().generate(); // Version 7 with per-call random values
 ```
 
 If you want customize generators, you may also just want to hold on to generator instance:

release-notes/VERSION

@@ -13,6 +13,9 @@ Releases
  (contributed by @magdel)
 #85: Fix `LazyRandom` for native code generation tools
  (contributed by @Maia-Everett)
+#94: Add alternate version to UUIDv7 generator that uses random values on every
+  call (not just for different timestamp)
+ (contributed by @magdel)
 
 4.3.0 (12-Sep-2023)
 

src/main/java/com/fasterxml/uuid/Generators.java

@@ -136,8 +136,10 @@ public static TimeBasedEpochGenerator timeBasedEpochGenerator()
      * Factory method for constructing UUID generator that generates UUID using
      * version 7 (Unix Epoch time+random based), using specified {@link Random}
      * number generator.
-     * Calls within same millisecond produce very similar values what may be
+     *<p>
+     * NOTE: calls within same millisecond produce very similar values; this may be
      * unsafe in some environments.
+     *<p>
      * No additional external synchronization is used.
      */
     public static TimeBasedEpochGenerator timeBasedEpochGenerator(Random random)
@@ -149,9 +151,11 @@ public static TimeBasedEpochGenerator timeBasedEpochGenerator(Random random)
      * Factory method for constructing UUID generator that generates UUID using
      * version 7 (Unix Epoch time+random based), using specified {@link Random}
      * number generator.
-     * Timestamp to use is accessed using specified {@link UUIDClock}
-     * Calls within same millisecond produce very similar values what may be
+     * Timestamp to use is accessed using specified {@link UUIDClock}.
+     *<p>
+     * NOTE: calls within same millisecond produce very similar values; this may be
      * unsafe in some environments.
+     *<p>
      * No additional external synchronization is used.
      *
      * @since 4.3
@@ -166,8 +170,13 @@ public static TimeBasedEpochGenerator timeBasedEpochGenerator(Random random,
      * Factory method for constructing UUID generator that generates UUID using
      * version 7 (Unix Epoch time+random based), using specified {@link Random}
      * number generator.
-     * Calls within same millisecond produce as random as possible values.
+     *<p>
+     * Calls within same millisecond use additional per-call randomness to try to create
+     * more distinct values, compared to {@link #timeBasedEpochGenerator(Random)}
+     *<p>
      * No additional external synchronization is used.
+     *
+     * @since 5.0
      */
     public static TimeBasedEpochRandomGenerator timeBasedEpochRandomGenerator(Random random)
     {
@@ -177,13 +186,15 @@ public static TimeBasedEpochRandomGenerator timeBasedEpochRandomGenerator(Random
     /**
      * Factory method for constructing UUID generator that generates UUID using
      * version 7 (Unix Epoch time+random based), using specified {@link Random}
-     * number generato.
+     * number generator.
      * Timestamp to use is accessed using specified {@link UUIDClock}
-     * Calls within same millisecond produce as random as possible values.
-     *
+     *<p>
+     * Calls within same millisecond use additional per-call randomness to try to create
+     * more distinct values, compared to {@link #timeBasedEpochGenerator(Random)}
+     *<p>
      * No additional external synchronization is used.
      *
-     * @since 4.3
+     * @since 5.0
      */
     public static TimeBasedEpochRandomGenerator timeBasedEpochRandomGenerator(Random random,
             UUIDClock clock)

src/main/java/com/fasterxml/uuid/impl/TimeBasedEpochRandomGenerator.java

@@ -25,7 +25,7 @@
  * {@link com.fasterxml.uuid.ext.FileBasedTimestampSynchronizer} (or
  * equivalent).
  *
- * @since 4.1
+ * @since 5.0
  */
 public class TimeBasedEpochRandomGenerator extends NoArgGenerator
 {
@@ -45,8 +45,6 @@ public class TimeBasedEpochRandomGenerator extends NoArgGenerator
     /**
      * Underlying {@link UUIDClock} used for accessing current time, to use for
      * generation.
-     *
-     * @since 4.3
      */
     protected final UUIDClock _clock;
 
@@ -117,8 +115,6 @@ public UUID generate()
      * @param rawTimestamp unix epoch millis
      *
      * @return unix epoch time based UUID
-     *
-     * @since 4.3
      */
     public UUID construct(long rawTimestamp)
     {

src/main/java/com/fasterxml/uuid/impl/UUIDUtil.java

@@ -362,7 +362,7 @@ private final static void _checkUUIDByteArray(byte[] bytes, int offset)
      *
      * @return timestamp in milliseconds (since Epoch), or 0 if type does not support timestamps
      *
-     * @since 5.0.0
+     * @since 5.0
      */
     public static long extractTimestamp(UUID uuid)
     {