Docs and make API more consistent

README.md

@@ -12,51 +12,46 @@ repositories {
 }
 
 dependencies {
- implementation("org.radarbase:radar-commons:0.15.0")
+ implementation("org.radarbase:radar-commons:1.0.0")
 }
 ```
 
 Example use, after adding [`radar-schemas`](https://github.com/radar-base/radar-schemas) to classpath:
+
 ```kotlin
 // Set URLs for RADAR-base installation
-val baseUrl = "..."
-val kafkaUrl = "$baseUrl/kafka/"
-val schemaUrl = "$baseUrl/schema/"
-val oauthHeaders = ...
-val key = ObservationKey("myProject", "myUser", "mySource")
-
-// Configure RADAR-base clients
-val client = RestClient.global().apply {
- server(ServerConfig(kafkaUrl))
- gzipCompression(true)
-}.build()
+val baseUrl = "https://..."
+val oauthToken = ...
+
+val kafkaSender = restKafkaSender {
+ baseUrl = "$baseUrl/kafka/"
+ headers.append("Authorization", "Bearer $oauthToken")
+ httpClient {
+ timeout(10.seconds)
+ }
+ schemaRetriever ("$baseUrl/schema/")
+}
 
-val schemaRetriever = SchemaRetriever(ServerConfig(schemaUrl), 30)
+// Configure topic to send data over
+val topic = AvroTopic(
+ "linux_raspberry_temperature",
+ ObservationKey.getClassSchema(),
+ RaspberryTemperature.getClassSchema(),
+ ObservationKey::class.java,
+ RaspberryTemperature::class.java
+)
 
-val restSender = RestSender.Builder().apply {
- httpClient(client)
- schemaRetriever(schemaRetriever)
- useBinaryContent(true)
- headers(oauthHeaders)
-}.build()
+val topicSender = kafkaSender.sender(topic)
 
-val sender = BatchedKafkaSender(restSender, 60_000L, 1000L)
+val key = ObservationKey("myProject", "myUser", "mySource")
 
-// Configure topic to send data over
-val topic = AvroTopic("linux_raspberry_temperature",
- ObservationKey.getClassSchema(), RaspberryTemperature.getClassSchema(),
- ObservationKey::class.java, RaspberryTemperature::class.java)
-
-// Send data to topic. Be sure to close
-// the sender after use. Preferably, a sender is reused
-// for many observations so that requests are efficiently
-// batched.
-sender.sender(topic).use { topicSender ->
- readValuesFromSystem() { value ->
- topicSender.send(key, value)
- }
+// Send data to topic.
+runBlocking {
+ val values: List<RaspberryTemperature> = readValuesFromSystem()
+ topicSender.send(key, values)
 }
 ```
+
 Note that this code above does not include any flows for registering a source with the ManagementPortal.
 
 For server utilities, include `radar-commons-server`:
@@ -67,7 +62,7 @@ repositories {
 }
 
 dependencies {
- implementation("org.radarbase:radar-commons-server:0.15.0")
+ implementation("org.radarbase:radar-commons-server:1.0.0")
 }
 ```
 
@@ -80,7 +75,7 @@ repositories {
 }
 
 dependencies {
- testImplementation("org.radarbase:radar-commons-testing:0.15.0")
+ testImplementation("org.radarbase:radar-commons-testing:1.0.0")
 }
 ```
 
@@ -107,9 +102,9 @@ configurations.all {
 }
 
 dependencies {
- implementation("org.radarbase:radar-commons:0.15.1-SNAPSHOT")
+ implementation("org.radarbase:radar-commons:1.0.1-SNAPSHOT")
 }
 ```
 
-Code should be formatted using the [Google Java Code Style Guide](https://google.github.io/styleguide/javaguide.html).
+Code should be formatted using the Kotlin official style guide, in addition to ktlint rules.
 If you want to contribute a feature or fix browse our [issues](https://github.com/RADAR-base/radar-commons/issues), and please make a pull request.

buildSrc/src/main/kotlin/Versions.kt

@@ -1,25 +1,25 @@
 object Versions {
- const val project = "0.16.0-SNAPSHOT"
+ const val project = "1.0.0"
 
  object Plugins {
- const val kotlin = "1.8.10"
+ const val kotlin = "1.8.21"
  const val kotlinSerialization = kotlin
- const val avro = "1.6.0"
+ const val avro = "1.7.0"
  }
 
  const val java = 11
  const val slf4j = "2.0.7"
  const val confluent = "7.3.2"
  const val kafka = "7.3.2-ce"
  const val avro = "1.11.1"
- const val jackson = "2.14.2"
- const val okhttp = "4.10.0"
- const val junit = "5.9.2"
- const val mockito = "5.2.0"
+ const val jackson = "2.15.0"
+ const val okhttp = "4.11.0"
+ const val junit = "5.9.3"
+ const val mockito = "5.3.1"
  const val mockitoKotlin = "4.1.0"
  const val hamcrest = "2.2"
  const val radarSchemas = "0.8.2"
  const val opencsv = "5.7.1"
- const val ktor = "2.2.4"
+ const val ktor = "2.3.0"
  const val coroutines = "1.6.4"
 }

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.0.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.1.1-bin.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradlew

@@ -85,9 +85,6 @@ done
 APP_BASE_NAME=${0##*/}
 APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
 
-# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
-
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum
 
@@ -197,6 +194,10 @@ if "$cygwin" || "$msys" ; then
  done
 fi
 
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
 # Collect all arguments for the java command;
 # * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
 # shell script including quotes and variable substitutions, so put them in

radar-commons-gradle/build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
  `maven-publish`
 }
 
-version = "0.16.0-SNAPSHOT"
+version = "1.0.0"
 group = "org.radarbase"
 description = "RADAR common Gradle plugins"
 
@@ -21,7 +21,7 @@ dependencies {
  implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.8.10")
  implementation("com.github.ben-manes:gradle-versions-plugin:0.46.0")
  implementation("io.github.gradle-nexus:publish-plugin:1.3.0")
- implementation("org.jlleitschuh.gradle:ktlint-gradle:11.3.1")
+ implementation("org.jlleitschuh.gradle:ktlint-gradle:11.3.2")
 }
 
 gradlePlugin {

radar-commons-gradle/src/main/kotlin/org/radarbase/gradle/plugin/Versions.kt

@@ -1,9 +1,9 @@
 package org.radarbase.gradle.plugin
 
 object Versions {
- const val wrapper = "8.0.2"
- const val kotlin = "1.8.10"
+ const val wrapper = "8.1.1"
+ const val kotlin = "1.8.21"
  const val ktlint = "0.48.2"
  const val java = 11
- const val junit = "5.9.2"
+ const val junit = "5.9.3"
 }

radar-commons-kotlin/src/main/kotlin/org/radarbase/kotlin/coroutines/CachedValue.kt

@@ -207,22 +207,26 @@ open class CachedValue<T>(
  cache.set(null)
  }
 
- @OptIn(ExperimentalTime::class)
- sealed class CacheContents<T>(
- time: TimeMark? = null,
- ) {
+ sealed class CacheContents<T>
+ @ExperimentalTime
+ constructor(time: TimeMark?) {
+
+ @OptIn(ExperimentalTime::class)
+ constructor() : this(null)
+
+ @ExperimentalTime
  protected val time: TimeMark = time ?: TimeSource.Monotonic.markNow()
 
+ @OptIn(ExperimentalTime::class)
  open fun isExpired(age: Duration): Boolean = (time + age).hasPassedNow()
 
  abstract fun getOrThrow(): T
 
- @Suppress("UNCHECKED_CAST")
  abstract suspend fun <R> map(transform: suspend (T) -> R): CacheContents<R>
  }
 
- @OptIn(ExperimentalTime::class)
- class CacheError<T> internal constructor(
+ class CacheError<T>
+ internal constructor(
  val exception: Throwable,
  ) : CacheContents<T>() {
  override fun isExpired(age: Duration): Boolean = exception is CancellationException || super.isExpired(age)
@@ -233,12 +237,19 @@ open class CachedValue<T>(
  }
 
  @OptIn(ExperimentalTime::class)
- class CacheValue<T> internal constructor(
+ class CacheValue<T>
+ @ExperimentalTime
+ internal constructor(
  val value: T,
- time: TimeMark? = null,
+ time: TimeMark?,
  ) : CacheContents<T>(time) {
+
+ @OptIn(ExperimentalTime::class)
+ constructor(value: T) : this(value, null)
+
  override fun getOrThrow(): T = value
 
+ @OptIn(ExperimentalTime::class)
  override suspend fun <R> map(transform: suspend (T) -> R): CacheContents<R> = try {
  CacheValue(transform(value), time = time)
  } catch (ex: Throwable) {

radar-commons/src/main/java/org/radarbase/producer/KafkaTopicSender.kt

@@ -21,7 +21,18 @@ interface KafkaTopicSender<K : Any, V : Any> {
  * @throws IOException if the client could not send a message
  */
  @Throws(IOException::class, SchemaValidationException::class)
- suspend fun send(key: K, value: V) = send(AvroRecordData(topic, key, listOf(value)))
+ suspend fun send(key: K, value: V) = send(key, listOf(value))
+
+ /**
+ * Send a message to Kafka eventually.
+ *
+ * @param key key of a kafka record to send
+ * @param values values for kafka records to send
+ * @throws AuthenticationException if the client failed to authenticate itself
+ * @throws IOException if the client could not send a message
+ */
+ @Throws(IOException::class, SchemaValidationException::class)
+ suspend fun send(key: K, values: List<V>) = send(AvroRecordData(topic, key, values))
 
  /**
  * Send a message to Kafka eventually. Contained offsets must be strictly monotonically

radar-commons/src/main/java/org/radarbase/producer/rest/RestKafkaSender.kt

@@ -227,6 +227,13 @@ class RestKafkaSender(config: Config) : KafkaSender {
  ?: HttpClient(CIO, config)
  }
 
+ fun schemaRetriever(schemaBaseUrl: String, builder: SchemaRetriever.Config.() -> Unit = {}) {
+ schemaRetriever = SchemaRetriever.schemaRetriever(schemaBaseUrl) {
+ httpClient = this@Config.httpClient
+ builder()
+ }
+ }
+
  override fun equals(other: Any?): Boolean {
  if (this === other) return true
  if (other == null || javaClass != other.javaClass) return false