JAVA-851: Improve UUIDs javadoc with regard to user-provided timestamps.

olim7t · olim7t · commit 6e5aea05bd19 · 2016-02-23T18:14:39.000+01:00
diff --git a/changelog/README.md b/changelog/README.md
@@ -14,6 +14,7 @@
 - [improvement] JAVA-833: Improve message when a nested type can't be serialized.
 - [improvement] JAVA-1011: Expose PoolingOptions default values.
 - [improvement] JAVA-630: Don't process DOWN events for nodes that have active connections.
+- [improvement] JAVA-851: Improve UUIDs javadoc with regard to user-provided timestamps.
 
 Merged from 2.0 branch:
 
diff --git a/driver-core/src/main/java/com/datastax/driver/core/utils/UUIDs.java b/driver-core/src/main/java/com/datastax/driver/core/utils/UUIDs.java
@@ -141,6 +141,16 @@ public static UUID random() {
      * UUID generated by this method are suitable for use with the
      * {@code timeuuid} Cassandra type. In particular the generated UUID
      * includes the timestamp of its generation.
+     * <p/>
+     * Note that there is no way to provide your own timestamp. This is deliberate, as we feel that this does not
+     * conform to the UUID specification, and therefore don't want to encourage it through the API.
+     * If you want to do it anyway, use the following workaround:
+     * <pre>
+     * Random random = new Random();
+     * UUID uuid = new UUID(UUIDs.startOf(userProvidedTimestamp).getMostSignificantBits(), random.nextLong());
+     * </pre>
+     * If you simply need to perform a range query on a {@code timeuuid} column, use the "fake" UUID generated by
+     * {@link #startOf(long)} and {@link #endOf(long)}.
      *
      * @return a new time-based UUID.
      */
@@ -157,14 +167,16 @@ public static UUID timeBased() {
      * <p/>
      * The UUID created by this method <b>are not unique</b> and as such are
      * <b>not</b> suitable for anything else than querying a specific time
-     * range. In particular, you should not insert such UUID.
+     * range. In particular, you should not insert such UUID. "True" UUID from
+     * user-provided timestamps are not supported (see {@link #timeBased()}
+     * for more explanations).
      * <p/>
      * Also, the timestamp to provide as parameter must be a unix timestamp (as
      * returned by {@link System#currentTimeMillis} or {@link java.util.Date#getTime}),
-     * not a UUID 100-nanoseconds intervals since 15 October 1582. In other
+     * not a UUID 100-nanoseconds interval since 15 October 1582. In other
      * words, given a UUID {@code uuid}, you should never do
      * {@code startOf(uuid.timestamp())} but rather
-     * {@code startOf(unixTimestamp(uuid.timestamp()))}.
+     * {@code startOf(unixTimestamp(uuid))}.
      * <p/>
      * Lastly, please note that Cassandra's timeuuid sorting is not compatible
      * with {@link UUID#compareTo} and hence the UUID created by this method
@@ -182,23 +194,7 @@ public static UUID startOf(long timestamp) {
      * Creates a "fake" time-based UUID that sorts as the biggest possible
      * version 1 UUID generated at the provided timestamp.
      * <p/>
-     * Such created UUID are useful in queries to select a time range of a
-     * {@code timeuuid} column.
-     * <p/>
-     * The UUID created by this method <b>are not unique</b> and as such are
-     * <b>not</b> suitable for anything else than querying a specific time
-     * range. In particular, you should not insert such UUID.
-     * <p/>
-     * Also, the timestamp to provide as parameter must be a unix timestamp (as
-     * returned by {@link System#currentTimeMillis} or {@link java.util.Date#getTime}),
-     * not a UUID 100-nanoseconds intervals since 15 October 1582. In other
-     * words, given a UUID {@code uuid}, you should never do
-     * {@code startOf(uuid.timestamp())} but rather
-     * {@code startOf(unixTimestamp(uuid.timestamp()))}.
-     * <p/>
-     * Lastly, please note that Cassandra's timeuuid sorting is not compatible
-     * with {@link UUID#compareTo} and hence the UUID created by this method
-     * are not necessarily upper bound for that latter method.
+     * See {@link #startOf(long)} for explanations about the intended usage of such UUID.
      *
      * @param timestamp the unix timestamp for which the created UUID must be an
      *                  upper bound.
