Merge pull request #761 from hexagontk/develop

Add extra and store modules

Author: jaguililla

README.md

@@ -15,7 +15,7 @@
       alt="GitHub Actions"
       src="https://github.com/hexagontk/hexagon/actions/workflows/release.yml/badge.svg" />
   </a>
-  <a href="https://hexagontk.com/jacoco">
+  <a href="https://hexagontk.com/stable/jacoco">
     <img src="https://hexagontk.com/stable/img/coverage.svg" alt="Coverage" />
   </a>
   <a href="https://search.maven.org/search?q=g:com.hexagontk">
@@ -25,7 +25,7 @@
 
 <p align="center">
   <a href="https://hexagontk.com">Home Site</a> |
-  <a href="https://hexagontk.com/quick_start">Quick Start</a>
+  <a href="https://hexagontk.com/stable/quick_start">Quick Start</a>
 </p>
 
 ---
@@ -430,23 +430,6 @@ You can check more sample projects and snippets at the [examples page].
 
 [examples page]: https://hexagontk.com/examples/example_projects
 
-## Thanks
-
-This project is supported by:
-
-<a href="https://www.digitalocean.com/?utm_medium=opensource&utm_source=Hexagon-Toolkit">
-  <img
-    height="128px"
-    src=
-      "https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_vertical_blue.svg">
-</a>
-
-<a href="https://www.jetbrains.com/?from=Hexagon-Toolkit">
-  <img
-    height="96px"
-    src="https://hexagontk.com/img/sponsors/jetbrains-variant-4.svg">
-</a>
-
 ## Status
 
 The toolkit is properly tested. This is the coverage report:
@@ -456,8 +439,8 @@ The toolkit is properly tested. This is the coverage report:
 Performance is not the primary goal, but it is taken seriously. You can check performance numbers
 in the [TechEmpower Web Framework Benchmarks][benchmark].
 
-[Coverage]: https://hexagontk.com/img/coverage.svg
-[CoverageReport]: https://hexagontk.com/jacoco
+[Coverage]: https://hexagontk.com/stable/img/coverage.svg
+[CoverageReport]: https://hexagontk.com/stable/jacoco
 [benchmark]: https://www.techempower.com/benchmarks
 
 ## Contribute
@@ -480,8 +463,6 @@ be up-to-date of project's news following [@hexagontk] on X (Twitter).
 
 Thanks to all project's [contributors]!
 
-[![CodeTriage](https://www.codetriage.com/hexagontk/hexagon/badges/users.svg)][CodeTriage]
-
 [give it a star]: https://github.com/hexagontk/hexagon/stargazers
 [discussions]: https://github.com/hexagontk/hexagon/discussions/categories/q-a
 [@hexagontk]: https://twitter.com/hexagontk
@@ -490,7 +471,6 @@ Thanks to all project's [contributors]!
 [contributing]: https://github.com/hexagontk/hexagon/contribute
 [Organization Board]: https://github.com/orgs/hexagontk/projects/2
 [contributors]: https://github.com/hexagontk/hexagon/graphs/contributors
-[CodeTriage]: https://www.codetriage.com/hexagontk/hexagon
 
 ## License
 

build.gradle.kts

@@ -59,7 +59,7 @@ mapOf(
 apply(from = "gradle/certificates.gradle")
 
 allprojects {
-    version = "4.0.4"
+    version = "4.1.0"
     group = "com.hexagontk"
 }
 

extra/jul/README.md

@@ -0,0 +1,24 @@
+
+# Module jul
+Contains logging utilities for the Java Util Logging package.
+
+### Install the Dependency
+
+=== "build.gradle"
+
+    ```groovy
+    implementation("com.hexagontk.extra:jul:$hexagonVersion")
+    ```
+
+=== "pom.xml"
+
+    ```xml
+    <dependency>
+      <groupId>com.hexagontk.extra</groupId>
+      <artifactId>jul</artifactId>
+      <version>$hexagonVersion</version>
+    </dependency>
+    ```
+
+# Package com.hexagontk.jul
+Provides helpers for the Java Util Logging library.

extra/jul/api/jul.api

@@ -0,0 +1,8 @@
+public final class com/hexagontk/jul/PatternFormat : java/util/logging/Formatter {
+	public static final field COLOR_PATTERN Ljava/lang/String;
+	public static final field PATTERN Ljava/lang/String;
+	public fun <init> (ZZ)V
+	public synthetic fun <init> (ZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun format (Ljava/util/logging/LogRecord;)Ljava/lang/String;
+}
+

extra/jul/build.gradle.kts

@@ -0,0 +1,18 @@
+
+plugins {
+    id("java-library")
+}
+
+apply(from = "$rootDir/gradle/kotlin.gradle")
+apply(from = "$rootDir/gradle/lean.gradle")
+
+apply(from = "$rootDir/gradle/publish.gradle")
+apply(from = "$rootDir/gradle/dokka.gradle")
+apply(from = "$rootDir/gradle/native.gradle")
+
+group = "com.hexagontk.extra"
+description = "Java Util Logging utilities."
+
+dependencies {
+    "api"(project(":core"))
+}

extra/jul/main/PatternFormat.kt

@@ -0,0 +1,85 @@
+package com.hexagontk.jul
+
+import com.hexagontk.core.text.AnsiColor.DEFAULT
+import com.hexagontk.core.text.AnsiColor.YELLOW
+import com.hexagontk.core.text.AnsiColor.BLUE
+import com.hexagontk.core.text.AnsiColor.BRIGHT_BLACK
+import com.hexagontk.core.text.AnsiColor.CYAN
+import com.hexagontk.core.text.AnsiColor.MAGENTA
+import com.hexagontk.core.text.AnsiColor.RED
+import com.hexagontk.core.text.AnsiEffect.BOLD
+import com.hexagontk.core.text.Ansi.RESET
+import com.hexagontk.core.text.eol
+import com.hexagontk.core.fail
+import com.hexagontk.core.toText
+import java.time.Instant
+import java.time.LocalDateTime
+import java.time.ZoneId
+import java.util.logging.Formatter
+import java.util.logging.Level
+import java.util.logging.LogRecord
+
+/**
+ * A Formatter implements [Formatter] provides support for formatting Logs.
+ *
+ * @property useColor Use colors in log messages.
+ */
+class PatternFormat(
+    private val useColor: Boolean,
+    private val messageOnly: Boolean = false,
+) : Formatter() {
+
+    internal companion object {
+        private const val TIMESTAMP = "%tH:%<tM:%<tS,%<tL"
+        private const val LEVEL = "%-5s"
+        private const val THREAD = "[%-15s]"
+        private const val LOGGER = "%-30s"
+
+        const val PATTERN = "$TIMESTAMP $LEVEL $THREAD $LOGGER | %s%n"
+        const val COLOR_PATTERN =
+            "$BRIGHT_BLACK$TIMESTAMP %s$LEVEL$RESET $MAGENTA$THREAD $CYAN$LOGGER$RESET | %s%n$RESET"
+    }
+
+    private val pattern: String = if (useColor) COLOR_PATTERN else PATTERN
+
+    private val levelColors: Map<Level, String> = mapOf(
+        Level.FINER to DEFAULT,
+        Level.FINE to DEFAULT,
+        Level.INFO to BLUE,
+        Level.WARNING to YELLOW,
+        Level.SEVERE to RED + BOLD
+    )
+
+    private val levelNames: Map<Level, String> = mapOf(
+        Level.FINER to "TRACE",
+        Level.FINE to "DEBUG",
+        Level.INFO to "INFO",
+        Level.WARNING to "WARN",
+        Level.SEVERE to "ERROR"
+    )
+
+    override fun format(record: LogRecord): String {
+        if (messageOnly)
+            return record.message + "\n"
+
+        val instant = Instant.ofEpochMilli(record.millis)
+        val dateTime = LocalDateTime.ofInstant(instant, ZoneId.systemDefault())
+        val thrown = record.thrown
+        val trace = when {
+            thrown == null -> ""
+            useColor -> "$eol${thrown.toText()}".replace("\n", "\n$RED")
+            else -> "$eol${thrown.toText()}"
+        }
+        val level = record.level
+        val levelName = levelNames[level] ?: fail
+        val levelColor = levelColors[level] ?: BLUE
+        val message = record.message
+        val loggerName = record.loggerName
+        val threadName = Thread.currentThread().name
+
+        return if (useColor)
+            pattern.format(dateTime, levelColor, levelName, threadName, loggerName, message + trace)
+        else
+            pattern.format(dateTime, levelName, threadName, loggerName, message + trace)
+    }
+}

extra/jul/main/SystemStreamHandler.kt

@@ -0,0 +1,29 @@
+package com.hexagontk.jul
+
+import java.io.PrintStream
+import java.util.logging.Formatter
+import java.util.logging.Level
+import java.util.logging.LogRecord
+import java.util.logging.StreamHandler
+
+/**
+ * Create a StreamHandler with a given [Formatter].
+ *
+ * @param handlerFormatter Formatter used by the log handler.
+ */
+internal class SystemStreamHandler(
+    handlerFormatter: Formatter,
+    stream: PrintStream = System.out
+) : StreamHandler() {
+
+    override fun publish(record: LogRecord) {
+        super.publish(record)
+        flush()
+    }
+
+    init {
+        setOutputStream(stream)
+        formatter = handlerFormatter
+        level = Level.ALL
+    }
+}

extra/jul/main/module-info.java

@@ -0,0 +1,12 @@
+/**
+ * This module holds utilities used in other libraries of the toolkit. Check the packages'
+ * documentation for more details. You can find a quick recap of the main features in the sections
+ * below.
+ */
+module com.hexagontk.jul {
+
+    requires transitive java.logging;
+    requires transitive com.hexagontk.core;
+
+    exports com.hexagontk.jul;
+}

extra/jul/test/PatternFormatTest.kt

@@ -0,0 +1,63 @@
+package com.hexagontk.jul
+
+import com.hexagontk.core.fail
+import com.hexagontk.core.text.AnsiColor
+import org.junit.jupiter.api.Assertions
+import org.junit.jupiter.api.Test
+import java.lang.RuntimeException
+import java.util.logging.Level.INFO
+import java.util.logging.Level.SEVERE
+import java.util.logging.LogRecord
+
+internal class PatternFormatTest {
+
+    @Test fun `Formatting messages with 'printf' special characters works correctly`() {
+        val message = "Message with '%'"
+
+        val colorFormat = PatternFormat(true)
+        val colorMessage = colorFormat.format(LogRecord(INFO, message))
+        Assertions.assertTrue(colorMessage.contains(message))
+        Assertions.assertTrue(colorMessage.contains(AnsiColor.BLUE))
+
+        val plainFormat = PatternFormat(false)
+        val plainMessage = plainFormat.format(LogRecord(INFO, message))
+        Assertions.assertTrue(plainMessage.contains(message))
+        Assertions.assertFalse(plainMessage.contains(AnsiColor.BLUE))
+    }
+
+    @Test fun `Formatting error messages render stack traces`() {
+        val message = "Message with '%'"
+        val record = LogRecord(SEVERE, message)
+        record.thrown = RuntimeException("Tested failure")
+
+        val colorMessage = PatternFormat(true).format(record)
+        Assertions.assertTrue(colorMessage.contains(message))
+        Assertions.assertTrue(colorMessage.contains(AnsiColor.RED))
+        Assertions.assertTrue(colorMessage.contains("Tested failure"))
+        Assertions.assertTrue(colorMessage.contains(RuntimeException::class.qualifiedName ?: fail))
+        Assertions.assertTrue(colorMessage.contains(this::class.qualifiedName ?: fail))
+
+        val plainMessage = PatternFormat(false).format(record)
+        Assertions.assertTrue(plainMessage.contains(message))
+        Assertions.assertFalse(plainMessage.contains(AnsiColor.RED))
+        Assertions.assertTrue(plainMessage.contains("Tested failure"))
+        Assertions.assertTrue(plainMessage.contains(RuntimeException::class.qualifiedName ?: fail))
+        Assertions.assertTrue(plainMessage.contains(this::class.qualifiedName ?: fail))
+    }
+
+    @Test fun `Formatting messages without logging fields works correctly`() {
+        val message = "Message with '%'"
+
+        val colorFormat = PatternFormat(useColor = true, messageOnly = true)
+        val colorMessage = colorFormat.format(LogRecord(INFO, message))
+        Assertions.assertTrue(colorMessage.contains(message))
+        Assertions.assertFalse(colorMessage.contains("INFO"))
+        Assertions.assertFalse(colorMessage.contains(AnsiColor.BLUE))
+
+        val plainFormat = PatternFormat(useColor = false, messageOnly = true)
+        val plainMessage = plainFormat.format(LogRecord(INFO, message))
+        Assertions.assertTrue(plainMessage.contains(message))
+        Assertions.assertFalse(colorMessage.contains("INFO"))
+        Assertions.assertFalse(plainMessage.contains(AnsiColor.BLUE))
+    }
+}

extra/jul/test/SystemStreamHandlerTest.kt

@@ -0,0 +1,25 @@
+package com.hexagontk.jul
+
+import org.junit.jupiter.api.Test
+import java.io.ByteArrayOutputStream
+import java.io.PrintStream
+import java.util.logging.Level.INFO
+import java.util.logging.LogRecord
+
+class SystemStreamHandlerTest {
+
+    @Test fun `Log records can be printed to a stream`() {
+        val output = ByteArrayOutputStream()
+        val record = LogRecord(INFO, "message")
+
+        SystemStreamHandler(PatternFormat(false), PrintStream(output)).publish(record)
+        assert(output.toByteArray().decodeToString().contains("message"))
+        output.flush()
+
+        val systemOut = System.out
+        System.setOut(PrintStream(output))
+        SystemStreamHandler(PatternFormat(false)).publish(record)
+        assert(output.toByteArray().decodeToString().contains("message"))
+        System.setOut(systemOut)
+    }
+}

extra/scheduler/README.md

@@ -0,0 +1,46 @@
+
+# Module scheduler
+Provides repeated tasks execution based on [Cron] expressions for Hexagon framework. It uses the
+[Cron-utils Java Library].
+
+!!! Note
+    In some platforms (i.e.: Kubernetes) there is a way to execute repeated tasks, you could take
+    advantage of them, as using your own service will raise problems scaling those services'
+    instances (you will have to coordinate them).
+
+This feature does not include any sort of synchronization if you have many instances of a scheduler
+service. If you want your scheduled jobs to be executed just once, you have to take care of
+synchronization yourself.
+
+### Install Dependency
+
+=== "build.gradle"
+
+    ```groovy
+    repositories {
+        mavenCentral()
+    }
+
+    implementation("com.hexagontk.extra:scheduler:$hexagonVersion")
+    ```
+
+=== "pom.xml"
+
+    ```xml
+    <dependency>
+      <groupId>com.hexagontk.extra</groupId>
+      <artifactId>scheduler</artifactId>
+      <version>$hexagonVersion</version>
+    </dependency>
+    ```
+
+### Example
+You can check a usage example in the following code:
+
+@code extra/scheduler/test/CronSchedulerTest.kt?sample
+
+# Package com.hexagontk.scheduler
+Classes for scheduling blocks of code repeatedly based on a [Cron] expression.
+
+[Cron]: https://en.wikipedia.org/wiki/Cron
+[Cron-utils Java Library]: http://cron-parser.com