From c6e40caf502b8d74a0b1878c1b26c4f657b6aa4b Mon Sep 17 00:00:00 2001 From: usbharu Date: Mon, 22 Apr 2024 15:58:51 +0900 Subject: [PATCH] =?UTF-8?q?doc:=20=E3=83=89=E3=82=AD=E3=83=A5=E3=83=A1?= =?UTF-8?q?=E3=83=B3=E3=83=88=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../common/property/BooleanPropertyValue.kt | 9 ++++ .../common/property/DoublePropertyValue.kt | 9 ++++ .../common/property/IntegerPropertyValue.kt | 9 ++++ .../common/property/PropertySerializeUtils.kt | 17 +++++++ .../owl/common/property/PropertyType.kt | 18 +++++++ .../owl/common/property/PropertyValue.kt | 7 +++ .../common/property/StringPropertyValue.kt | 9 ++++ .../common/retry/ExponentialRetryPolicy.kt | 8 +++- .../usbharu/owl/common/retry/RetryPolicy.kt | 13 +++++ .../owl/common/task/PropertyDefinition.kt | 12 +++++ .../usbharu/owl/common/task/PublishedTask.kt | 10 +++- .../dev/usbharu/owl/common/task/Task.kt | 4 ++ .../usbharu/owl/common/task/TaskDefinition.kt | 47 +++++++++++++++++++ 13 files changed, 170 insertions(+), 2 deletions(-) diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/property/BooleanPropertyValue.kt b/common/src/main/kotlin/dev/usbharu/owl/common/property/BooleanPropertyValue.kt index 0a04685a..b595f31c 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/property/BooleanPropertyValue.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/property/BooleanPropertyValue.kt @@ -1,10 +1,19 @@ package dev.usbharu.owl.common.property +/** + * Boolean型のプロパティ + * + * @property value プロパティ + */ class BooleanPropertyValue(override val value: Boolean) : PropertyValue() { override val type: PropertyType get() = PropertyType.binary } +/** + * [BooleanPropertyValue]のシリアライザー + * + */ class BooleanPropertySerializer : PropertySerializer { override fun isSupported(propertyValue: PropertyValue<*>): Boolean { return propertyValue.value is Boolean diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/property/DoublePropertyValue.kt b/common/src/main/kotlin/dev/usbharu/owl/common/property/DoublePropertyValue.kt index 13156f20..c201cbaa 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/property/DoublePropertyValue.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/property/DoublePropertyValue.kt @@ -1,10 +1,19 @@ package dev.usbharu.owl.common.property +/** + * Double型のプロパティ + * + * @property value プロパティ + */ class DoublePropertyValue(override val value: Double) : PropertyValue() { override val type: PropertyType get() = PropertyType.number } +/** + * [DoublePropertyValue]のシリアライザー + * + */ class DoublePropertySerializer : PropertySerializer { override fun isSupported(propertyValue: PropertyValue<*>): Boolean { return propertyValue.value is Double diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/property/IntegerPropertyValue.kt b/common/src/main/kotlin/dev/usbharu/owl/common/property/IntegerPropertyValue.kt index 42782069..9b49c39c 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/property/IntegerPropertyValue.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/property/IntegerPropertyValue.kt @@ -16,11 +16,20 @@ package dev.usbharu.owl.common.property +/** + * Integer型のプロパティ + * + * @property value プロパティ + */ class IntegerPropertyValue(override val value: Int) : PropertyValue() { override val type: PropertyType get() = PropertyType.number } +/** + * [IntegerPropertyValue]のシリアライザー + * + */ class IntegerPropertySerializer : PropertySerializer { override fun isSupported(propertyValue: PropertyValue<*>): Boolean { return propertyValue.value is Int diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertySerializeUtils.kt b/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertySerializeUtils.kt index 38d7a4b8..248e63f2 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertySerializeUtils.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertySerializeUtils.kt @@ -16,13 +16,30 @@ package dev.usbharu.owl.common.property +/** + * [PropertySerializer]のユーティリティークラス + */ object PropertySerializeUtils { + /** + * Stringと[PropertyValue]の[Map]から[PropertyValue]をシリアライズし、StringとStringの[Map]として返します + * + * @param serializerFactory シリアライズに使用する[PropertySerializerFactory] + * @param properties シリアライズする[Map] + * @return Stringとシリアライズ済みの[PropertyValue]の[Map] + */ fun serialize( serializerFactory: PropertySerializerFactory, properties: Map> ): Map = properties.map { it.key to serializerFactory.factory(it.value).serialize(it.value) }.toMap() + /** + * Stringとシリアライズ済みの[PropertyValue]の[Map]からシリアライズ済みの[PropertyValue]をデシリアライズし、Stringと[PropertyValue]の[Map]として返します + * + * @param serializerFactory デシリアライズに使用する[PropertySerializerFactory] + * @param properties デシリアライズする[Map] + * @return Stringと[PropertyValue]の[Map] + */ fun deserialize( serializerFactory: PropertySerializerFactory, properties: Map diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyType.kt b/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyType.kt index c9dabae5..4259c62f 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyType.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyType.kt @@ -16,8 +16,26 @@ package dev.usbharu.owl.common.property +/** + * プロパティの型 + * + */ enum class PropertyType { + /** + * 数字 + * + */ number, + + /** + * 文字列 + * + */ string, + + /** + * バイナリ + * + */ binary } \ No newline at end of file diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyValue.kt b/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyValue.kt index f5fc04f7..c251c54f 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyValue.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/property/PropertyValue.kt @@ -22,6 +22,13 @@ package dev.usbharu.owl.common.property * @param T プロパティの型 */ sealed class PropertyValue { + /** + * プロパティ + */ abstract val value: T + + /** + * プロパティの型 + */ abstract val type: PropertyType } \ No newline at end of file diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/property/StringPropertyValue.kt b/common/src/main/kotlin/dev/usbharu/owl/common/property/StringPropertyValue.kt index a7030d22..5b4cbaa1 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/property/StringPropertyValue.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/property/StringPropertyValue.kt @@ -1,10 +1,19 @@ package dev.usbharu.owl.common.property +/** + * String型のプロパティ + * + * @property value プロパティ + */ class StringPropertyValue(override val value: String) : PropertyValue() { override val type: PropertyType get() = PropertyType.string } +/** + * [StringPropertyValue]のシリアライザー + * + */ class StringPropertyValueSerializer : PropertySerializer { override fun isSupported(propertyValue: PropertyValue<*>): Boolean { return propertyValue.value is String diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/retry/ExponentialRetryPolicy.kt b/common/src/main/kotlin/dev/usbharu/owl/common/retry/ExponentialRetryPolicy.kt index 753746db..b34cacf5 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/retry/ExponentialRetryPolicy.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/retry/ExponentialRetryPolicy.kt @@ -4,8 +4,14 @@ import java.time.Instant import kotlin.math.pow import kotlin.math.roundToLong +/** + * 指数関数的に待機時間が増えるリトライポリシー + * `firstRetrySeconds x attempt ^ 2 - firstRetrySeconds` + * + * @property firstRetrySeconds + */ class ExponentialRetryPolicy(private val firstRetrySeconds: Int = 30) : RetryPolicy { override fun nextRetry(now: Instant, attempt: Int): Instant = - now.plusSeconds(firstRetrySeconds.times((2.0).pow(attempt).roundToLong()) - 30) + now.plusSeconds(firstRetrySeconds.times((2.0).pow(attempt).roundToLong()) - firstRetrySeconds) } \ No newline at end of file diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/retry/RetryPolicy.kt b/common/src/main/kotlin/dev/usbharu/owl/common/retry/RetryPolicy.kt index 04a73a00..da6e4ec0 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/retry/RetryPolicy.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/retry/RetryPolicy.kt @@ -18,6 +18,19 @@ package dev.usbharu.owl.common.retry import java.time.Instant +/** + * リトライポリシー + * + */ interface RetryPolicy { + /** + * 次のリトライ時刻を返します。 + * + * [attempt]を負の値にしてはいけません + * + * @param now 現在の時刻 + * @param attempt 試行回数 + * @return 次のリトライ時刻 + */ fun nextRetry(now: Instant, attempt: Int): Instant } \ No newline at end of file diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/task/PropertyDefinition.kt b/common/src/main/kotlin/dev/usbharu/owl/common/task/PropertyDefinition.kt index 11f8dcda..cbc96b0b 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/task/PropertyDefinition.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/task/PropertyDefinition.kt @@ -18,7 +18,19 @@ package dev.usbharu.owl.common.task import dev.usbharu.owl.common.property.PropertyType +/** + * プロパティ定義 + * + * @property map プロパティ名とプロパティタイプの[Map] + */ class PropertyDefinition(val map: Map) : Map by map { + /** + * プロパティ定義のハッシュを求めます + * + * ハッシュ値はプロパティ名とプロパティタイプ名を結合したものを結合し、各文字のUTF-16コードと31を掛け続けたものです。 + * + * @return + */ fun hash(): Long { var hash = 1L map.map { it.key + it.value.name }.joinToString("").map { hash *= it.code * 31 } diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/task/PublishedTask.kt b/common/src/main/kotlin/dev/usbharu/owl/common/task/PublishedTask.kt index 57d55ecb..a0f944e5 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/task/PublishedTask.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/task/PublishedTask.kt @@ -17,8 +17,16 @@ package dev.usbharu.owl.common.task import java.time.Instant -import java.util.UUID +import java.util.* +/** + * 公開済みのタスク + * + * @param T タスク + * @property task タスク + * @property id タスクのID + * @property published 公開された時刻 + */ data class PublishedTask( val task: T, val id: UUID, diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/task/Task.kt b/common/src/main/kotlin/dev/usbharu/owl/common/task/Task.kt index 2f196e8e..42d8dc03 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/task/Task.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/task/Task.kt @@ -16,5 +16,9 @@ package dev.usbharu.owl.common.task +/** + * タスク + * + */ open class Task { } \ No newline at end of file diff --git a/common/src/main/kotlin/dev/usbharu/owl/common/task/TaskDefinition.kt b/common/src/main/kotlin/dev/usbharu/owl/common/task/TaskDefinition.kt index d62b94de..b96c12de 100644 --- a/common/src/main/kotlin/dev/usbharu/owl/common/task/TaskDefinition.kt +++ b/common/src/main/kotlin/dev/usbharu/owl/common/task/TaskDefinition.kt @@ -18,15 +18,62 @@ package dev.usbharu.owl.common.task import dev.usbharu.owl.common.property.PropertyValue +/** + * タスク定義 + * + * @param T タスク + */ interface TaskDefinition { + /** + * タスク名 + */ val name: String + + /** + * 優先度 + */ val priority: Int + + /** + * 最大リトライ数 + */ val maxRetry: Int + + /** + * リトライポリシー名 + * + * ポリシーの解決は各Brokerに依存しています + */ val retryPolicy: String + + /** + * タスク実行時のタイムアウト(ミリ秒) + */ val timeoutMilli: Long + + /** + * プロパティ定義 + */ val propertyDefinition: PropertyDefinition + + /** + * [Task]の[Class] + */ val type: Class + /** + * タスクをシリアライズします. + * プロパティのシリアライズと混同しないようにしてください。 + * @param task シリアライズするタスク + * @return シリアライズされたタスク + */ fun serialize(task: T): Map> + + /** + * タスクをデシリアライズします。 + * プロパティのデシリアライズと混同しないようにしてください + * @param value デシリアライズするタスク + * @return デシリアライズされたタスク + */ fun deserialize(value: Map>): T } \ No newline at end of file