Merge branch 'develop': release 1.5

Author: frost13it

README.md

@@ -23,9 +23,19 @@ kinfra-commons
 
 Более безопасная альтернатива `Optional.orElse(null)`: возвращаемый тип - `T?`, а не `T!`.
 
+### Работа с time-based UUID
+
+#### generateTimeBasedUuid()
+
+Создаёт новый time-based UUID.
+
+#### UUID.isTimeBased
+
+Определяет, является ли данный UUID time-based (версии 1).
+
 #### UUID.instant()
 
-Возвращает `Instant`, соответствующий полю `timestamp` UUID версии 4 (time-based).
+Возвращает `Instant`, соответствующий полю `timestamp`.
 
 ### Работа с `enum class`
 

build.gradle

@@ -1,29 +1,22 @@
 plugins {
-    id 'ru.kontur.library' version '4.4'
-    id 'org.jetbrains.kotlin.jvm' version '1.3.61'
+    id 'ru.kontur.library' version '5.6'
+    id 'org.jetbrains.kotlin.jvm' version '1.4.32'
 }
 
 ext {
-    release = '1.4'
+    release = '1.5'
 
     versions = [
         assertj: '3.14.0',
-        coroutines: '1.3.3',
+        coroutines: '1.4.3',
     ]
-
-    branch = project.properties["branch"]?.toString()
-    isStableBranch = (branch == "master") || branch?.startsWith("release-")
-    version = release + (isStableBranch ? '' : '-SNAPSHOT')
 }
 
 group = "ru.kontur.kinfra"
-version = ext.version
-
-sourceCompatibility = 8
+version = buildVersion(release) { libraryDefaults() }
 
 dependencies {
-    allMain platform("org.jetbrains.kotlinx:kotlinx-coroutines-bom:${versions.coroutines}")
-
+    implementation platform("org.jetbrains.kotlinx:kotlinx-coroutines-bom:${versions.coroutines}")
     implementation "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8"
 
     testImplementation "org.assertj:assertj-core:${versions.assertj}"

gradle/wrapper/gradle-wrapper.jar

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.1.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradle/wrapper/gradle-wrapper.properties

@@ -82,6 +82,7 @@ esac
 
 CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
 
+
 # Determine the Java command to use to start the JVM.
 if [ -n "$JAVA_HOME" ] ; then
     if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
@@ -125,10 +126,11 @@ if $darwin; then
     GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
 fi
 
-# For Cygwin, switch paths to Windows format before running java
-if $cygwin ; then
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then
     APP_HOME=`cygpath --path --mixed "$APP_HOME"`
     CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
+
     JAVACMD=`cygpath --unix "$JAVACMD"`
 
     # We build the pattern for arguments to be converted via cygpath
@@ -154,19 +156,19 @@ if $cygwin ; then
         else
             eval `echo args$i`="\"$arg\""
         fi
-        i=$((i+1))
+        i=`expr $i + 1`
     done
     case $i in
-        (0) set -- ;;
-        (1) set -- "$args0" ;;
-        (2) set -- "$args0" "$args1" ;;
-        (3) set -- "$args0" "$args1" "$args2" ;;
-        (4) set -- "$args0" "$args1" "$args2" "$args3" ;;
-        (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
-        (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
-        (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
-        (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
-        (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
+        0) set -- ;;
+        1) set -- "$args0" ;;
+        2) set -- "$args0" "$args1" ;;
+        3) set -- "$args0" "$args1" "$args2" ;;
+        4) set -- "$args0" "$args1" "$args2" "$args3" ;;
+        5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
+        6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
+        7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
+        8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
+        9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
     esac
 fi
 
@@ -175,14 +177,9 @@ save () {
     for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
     echo " "
 }
-APP_ARGS=$(save "$@")
+APP_ARGS=`save "$@"`
 
 # Collect all arguments for the java command, following the shell quoting and substitution rules
 eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
 
-# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
-if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then
-  cd "$(dirname "$0")"
-fi
-
 exec "$JAVACMD" "$@"

gradlew

@@ -29,6 +29,9 @@ if "%DIRNAME%" == "" set DIRNAME=.
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
 @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
 set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
 
@@ -37,7 +40,7 @@ if defined JAVA_HOME goto findJavaFromJavaHome
 
 set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto init
+if "%ERRORLEVEL%" == "0" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
@@ -51,7 +54,7 @@ goto fail
 set JAVA_HOME=%JAVA_HOME:"=%
 set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
-if exist "%JAVA_EXE%" goto init
+if exist "%JAVA_EXE%" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
@@ -61,28 +64,14 @@ echo location of your Java installation.
 
 goto fail
 
-:init
-@rem Get command-line arguments, handling Windows variants
-
-if not "%OS%" == "Windows_NT" goto win9xME_args
-
-:win9xME_args
-@rem Slurp the command line arguments.
-set CMD_LINE_ARGS=
-set _SKIP=2
-
-:win9xME_args_slurp
-if "x%~1" == "x" goto execute
-
-set CMD_LINE_ARGS=%*
-
 :execute
 @rem Setup the command line
 
 set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
 
+
 @rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
 
 :end
 @rem End local scope for the variables with windows NT shell

gradlew.bat

@@ -1,6 +1,5 @@
 package ru.kontur.kinfra.commons
 
-import ru.kontur.kinfra.commons.time.TimeTicks
 import java.time.Instant
 import java.util.*
 
@@ -11,12 +10,8 @@ import java.util.*
  */
 fun <T> Optional<T>.unwrap(): T? = orElse(null)
 
-/**
- * Return timestamp of this time-based (version 1) UUID as an [Instant].
- *
- * @throws UnsupportedOperationException if this UUID is not time-based
- * @see UUID.timestamp
- */
-fun UUID.instant(): Instant {
-    return TimeTicks.UuidTimestamp(timestamp()).toInstant()
+@Deprecated(message = "for compatibility", level = DeprecationLevel.HIDDEN)
+@JvmName("instant")
+fun UUID.instantCompatibilityBridge(): Instant {
+    return instant()
 }

src/main/kotlin/ru/kontur/kinfra/commons/JdkExtensions.kt

@@ -0,0 +1,116 @@
+package ru.kontur.kinfra.commons
+
+import ru.kontur.kinfra.commons.time.TimeTicks
+import ru.kontur.kinfra.commons.time.toTicks
+import ru.kontur.kinfra.commons.time.toUuidTime
+import java.time.Clock
+import java.time.Duration
+import java.time.Instant
+import java.util.*
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Determines if this UUID is time-based (version 1)
+ */
+val UUID.isTimeBased: Boolean
+    get() = version() == 1
+
+/**
+ * Return timestamp of this time-based (version 1) UUID as an [Instant].
+ *
+ * @throws UnsupportedOperationException if this UUID is not time-based
+ * @see UUID.timestamp
+ */
+fun UUID.instant(): Instant {
+    return TimeTicks.UuidTimestamp(timestamp()).toInstant()
+}
+
+/**
+ * Creates a new time-based (version 1) UUID.
+ */
+fun generateTimeBasedUuid(): UUID {
+    return TimeBasedUuidGenerator.generate()
+}
+
+internal object TimeBasedUuidGenerator {
+    // See https://www.ietf.org/rfc/rfc4122.html
+
+    private val random = Random()
+    private val timeSource = Clock.systemUTC()
+    private val timestampAccuracy = Duration.ofMillis(1).toTicks().value
+
+    private val lastTimestamp = AtomicLong()
+    private val lsb = AtomicLong(generateLsb())
+
+    fun generate(): UUID {
+        val timestamp: Long
+        var currentLsb: Long
+        while (true) {
+            val last = lastTimestamp.get()
+            val now = timeSource.instant().toUuidTime().value
+            // Validity of this value is checked by CAS on lastTimestamp
+            currentLsb = lsb.get()
+            if (now > last) {
+                if (lastTimestamp.compareAndSet(last, now)) {
+                    timestamp = now
+                    break
+                }
+            } else if (now + timestampAccuracy > last) {
+                val next = last + 1
+                // Use a next timestamp value as long as it does not go far from the current time
+                if (now + timestampAccuracy > next) {
+                    if (lastTimestamp.compareAndSet(last, next)) {
+                        timestamp = next
+                        break
+                    }
+                } else {
+                    // Wait for a next timestamp from system clock
+                    Thread.yield()
+                }
+            } else {
+                // Last timestamp is much greater than current time
+                // Hence the clock jumped backwards
+                // Generate a new clock sequence and node to safely reuse the same timestamps
+                val newLsb = generateLsb()
+                if (lsb.compareAndSet(currentLsb, newLsb)) {
+                    currentLsb = newLsb
+                    if (lastTimestamp.compareAndSet(last, now)) {
+                        timestamp = now
+                        break
+                    }
+                }
+            }
+        }
+        return UUID(makeMsb(timestamp), currentLsb)
+    }
+
+    fun makeMsb(timestamp: Long): Long {
+        require(timestamp ushr 60 == 0L) { "Invalid timestamp: $timestamp" }
+
+        val hiMask = makeMask(12) shl 48
+        val midMask = makeMask(16) shl 32
+        val lowMask = makeMask(32)
+        return timestamp.and(lowMask).shl(32) or
+            timestamp.and(midMask).ushr(16) or
+            timestamp.and(hiMask).ushr(48) or
+            (1 shl 12)
+    }
+
+    private fun generateLsb(): Long {
+        val variant = 1L shl 63
+        val clock = (random.nextInt() and 0x3fff).toLong() shl 48
+        // Random node is used, as described in section 4.5
+        val node = run {
+            val randomData = random.nextLong()
+            val macMask = makeMask(48)
+            val multicastBit = 1L shl 40
+            multicastBit or (randomData and macMask)
+        }
+        return variant or clock or node
+    }
+
+    private fun makeMask(bitSize: Int): Long {
+        return (1L shl bitSize) - 1
+    }
+
+}

src/main/kotlin/ru/kontur/kinfra/commons/TimeBasedUuid.kt

@@ -1,29 +1,41 @@
 package ru.kontur.kinfra.commons.binary
 
-private val hexDigits = "0123456789abcdef".toCharArray()
+private val hexDigitsLower = "0123456789abcdef".toCharArray()
+private val hexDigitsUpper = "0123456789ABCDEF".toCharArray()
 
 /**
  * Returns this byte in form of two hexadecimal digits.
  */
-fun Byte.toHexString(): String {
+fun Byte.toHexString(upperCase: Boolean = false): String {
     val unsigned = asUnsigned()
+    val hexDigits = if (upperCase) hexDigitsUpper else hexDigitsLower
     val chars = CharArray(2)
     chars[0] = hexDigits[unsigned shr 4]
     chars[1] = hexDigits[unsigned and 0xF]
     return String(chars)
 }
 
+@Deprecated(message = "for compatibility", level = DeprecationLevel.HIDDEN)
+fun Byte.toHexString(): String {
+    return toHexString(upperCase = false)
+}
+
 /**
  * Returns hexadecimal representation of bytes in this array.
  *
  * Inverse transformation is possible with [byteArrayOfHex].
  */
-fun ByteArray.toHexString(): String = buildString(size * 2) {
+fun ByteArray.toHexString(upperCase: Boolean = false): String = buildString(size * 2) {
     for (byte in this@toHexString) {
-        appendHexByte(byte)
+        appendHexByte(byte, upperCase)
     }
 }
 
+@Deprecated(message = "for compatibility", level = DeprecationLevel.HIDDEN)
+fun ByteArray.toHexString(): String {
+    return toHexString(upperCase = false)
+}
+
 /**
  * Constructs array of bytes from its hexadecimal representation.
  *
@@ -45,10 +57,16 @@ fun byteArrayOfHex(hex: String): ByteArray {
 
 /**
  * Append hexadecimal representation of a [byte] to this builder.
- * Exactly two hexadecimal digits in lower case are appended.
+ * Exactly two hexadecimal digits are appended.
  */
-fun StringBuilder.appendHexByte(byte: Byte) {
+fun StringBuilder.appendHexByte(byte: Byte, upperCase: Boolean = false) {
     val unsigned = byte.asUnsigned()
+    val hexDigits = if (upperCase) hexDigitsUpper else hexDigitsLower
     append(hexDigits[unsigned shr 4])
     append(hexDigits[unsigned and 0xF])
 }
+
+@Deprecated(message = "for compatibility", level = DeprecationLevel.HIDDEN)
+fun StringBuilder.appendHexByte(byte: Byte) {
+    appendHexByte(byte, upperCase = false)
+}