Make the Java validation extendable

build.gradle.kts

@@ -58,6 +58,7 @@ spinePublishing {
         "java",
         "java-bundle",
         "java-runtime",
+        "java-api"
     )
     modulesWithCustomPublishing = setOf(
         "java-bundle",

java-tests/extensions/src/main/kotlin/io/spine/validation/test/MoneyValidationPlugin.kt → java-api/build.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2024, TeamDev. All rights reserved.
+ * Copyright 2025, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,12 +24,9 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-package io.spine.validation.test
+import io.spine.dependency.local.ProtoData
 
-import io.spine.protodata.plugin.Plugin
-
-@Suppress("unused") // Accessed reflectively by ProtoData.
-public class MoneyValidationPlugin : Plugin(
-    viewRepositories = setOf(CurrencyTypeView.Repo()),
-    policies = setOf(CurrencyValidationPolicy())
-)
+dependencies {
+    api(ProtoData.java)
+    api(project(":proto:context"))
+}

java-api/src/main/kotlin/io/spine/validation/api/OptionName.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+/**
+ * Path to the name field in `*OptionDiscovered` events.
+ *
+ * The main purpose of this constant is to set the field path when
+ * filtering incoming events by the option name. It is usually used
+ * in a pair with the constant containing the option name.
+ *
+ * An example of event filtering in a policy:
+ *
+ * ```
+ *     @React
+ *     override fun whenever(
+ *         @External @Where(field = OPTION_NAME, equals = REQUIRED)
+ *         event: FieldOptionDiscovered,
+ *     ): EitherOf2<RequiredFieldDiscovered, NoReaction> {
+ * ```
+ */
+public const val OPTION_NAME: String = "option.name"

model/src/main/kotlin/io/spine/validation/UnsetValue.kt → java-api/src/main/kotlin/io/spine/validation/api/UnsetValue.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2024, TeamDev. All rights reserved.
+ * Copyright 2025, TeamDev. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-package io.spine.validation
+package io.spine.validation.api
 
 import com.google.protobuf.ByteString
 import io.spine.protodata.ast.Cardinality.CARDINALITY_LIST
@@ -56,6 +56,8 @@ import io.spine.string.shortly
  * This class does not instantiate default values of Protobuf messages. It merely creates
  * instances of [Value] which represent values of Protobuf message fields, which are not set.
  */
+// TODO:2025-03-12:yevhenii.nadtochii: `EmptyFieldCheck` should not need this object.
+//  See issue: https://github.com/SpineEventEngine/validation/issues/199
 public object UnsetValue {
 
     /**

java-api/src/main/kotlin/io/spine/validation/api/ValidationOption.kt

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import io.spine.annotation.SPI
+import io.spine.protodata.plugin.Policy
+import io.spine.protodata.plugin.View
+import io.spine.validation.api.generate.OptionGenerator
+
+/**
+ * Extends the Java validation library with the custom validation option.
+ */
+@SPI
+public interface ValidationOption {
+
+    /**
+     * The [policies][Policy] added by the option.
+     */
+    public val policy: Set<Policy<*>>
+
+    /**
+     * The [views][View] added by the option.
+     */
+    public val view: Set<Class<out View<*, *, *>>>
+
+    /**
+     * The option [generator][OptionGenerator] for Java.
+     */
+    public val generator: OptionGenerator
+}

java/src/main/kotlin/io/spine/validation/java/expression/AnnotatedClassNames.kt → java-api/src/main/kotlin/io/spine/validation/api/expression/AnnotatedClassNames.kt

@@ -24,7 +24,7 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-package io.spine.validation.java.expression
+package io.spine.validation.api.expression
 
 import io.spine.protodata.java.AnnotatedClassName
 import io.spine.protodata.java.ClassName
@@ -33,9 +33,10 @@ import org.checkerframework.checker.nullness.qual.Nullable
 /**
  * The [ClassName] of [org.checkerframework.checker.nullness.qual.Nullable].
  */
-internal val NullableAnnotation = ClassName(Nullable::class)
+public val NullableAnnotation: ClassName = ClassName(Nullable::class)
 
 /**
  * The [TypeNameClass] annotated with [NullableAnnotation].
  */
-internal val NullableTypeNameClass = AnnotatedClassName(TypeNameClass, NullableAnnotation)
+public val NullableTypeNameClass: AnnotatedClassName =
+    AnnotatedClassName(TypeNameClass, NullableAnnotation)

java/src/main/kotlin/io/spine/validation/java/expression/ClassNames.kt → java-api/src/main/kotlin/io/spine/validation/api/expression/ClassNames.kt

@@ -26,7 +26,7 @@
 
 @file:JvmName("ClassNames")
 
-package io.spine.validation.java.expression
+package io.spine.validation.api.expression
 
 import com.google.common.collect.ImmutableList
 import com.google.common.collect.ImmutableSet
@@ -53,52 +53,52 @@ import java.util.stream.Collectors
 /**
  * The [ClassName] of [String].
  */
-internal val StringClass = ClassName(String::class)
+public val StringClass: ClassName = ClassName(String::class)
 
 /**
  * The [ClassName] of [Collectors].
  */
-internal val CollectorsClass = ClassName(Collectors::class)
+public val CollectorsClass: ClassName = ClassName(Collectors::class)
 
 /**
  * The [ClassName] of [TemplateString].
  */
-internal val TemplateStringClass = ClassName(TemplateString::class)
+public val TemplateStringClass: ClassName = ClassName(TemplateString::class)
 
 /**
  * The [ClassName] of [Pattern].
  */
-internal val PatternClass = ClassName(Pattern::class)
+public val PatternClass: ClassName = ClassName(Pattern::class)
 
 /**
  * The [ClassName] of [ImmutableList].
  */
-internal val ImmutableListClass = ClassName(ImmutableList::class)
+public val ImmutableListClass: ClassName = ClassName(ImmutableList::class)
 
 /**
  * The [ClassName] of [ImmutableSet].
  */
-internal val ImmutableSetClass = ClassName(ImmutableSet::class)
+public val ImmutableSetClass: ClassName = ClassName(ImmutableSet::class)
 
 /**
  * The [ClassName] of [LinkedHashMultiset].
  */
-internal val LinkedHashMultisetClass = ClassName(LinkedHashMultiset::class)
+public val LinkedHashMultisetClass: ClassName = ClassName(LinkedHashMultiset::class)
 
 /**
  * The [ClassName] of [Multiset.Entry] class.
  */
-internal val MultiSetEntryClass = ClassName(Multiset.Entry::class)
+public val MultiSetEntryClass: ClassName = ClassName(Multiset.Entry::class)
 
 /**
  * The [ClassName] of [FieldPath].
  */
-internal val FieldPathClass = ClassName(FieldPath::class)
+public val FieldPathClass: ClassName = ClassName(FieldPath::class)
 
 /**
  * The [ClassName] of [ConstraintViolation].
  */
-internal val ConstraintViolationClass = ClassName(ConstraintViolation::class)
+public val ConstraintViolationClass: ClassName = ClassName(ConstraintViolation::class)
 
 /**
  * The [ClassName] of `io.spine.base.FieldPaths`.
@@ -107,69 +107,69 @@ internal val ConstraintViolationClass = ClassName(ConstraintViolation::class)
  * declared for [FieldPath]. It is available from Java, but not from Kotlin.
  * So, we specify it as a string literal here.
  */
-internal val FieldPathsClass = ClassName("io.spine.base", "FieldPaths")
+public val FieldPathsClass: ClassName = ClassName("io.spine.base", "FieldPaths")
 
 /**
  * The [ClassName] of [ValidationError].
  */
-internal val ValidationErrorClass = ClassName(ValidationError::class)
+public val ValidationErrorClass: ClassName = ClassName(ValidationError::class)
 
 /**
  * The [ClassName] of [ValidatableMessage].
  */
-internal val ValidatableMessageClass = ClassName(ValidatableMessage::class)
+public val ValidatableMessageClass: ClassName = ClassName(ValidatableMessage::class)
 
 /**
  * The [ClassName] of [AnyPacker].
  */
-internal val AnyPackerClass = ClassName(AnyPacker::class)
+public val AnyPackerClass: ClassName = ClassName(AnyPacker::class)
 
 /**
  * The [ClassName] of [Message].
  */
-internal val MessageClass = ClassName(Message::class)
+public val MessageClass: ClassName = ClassName(Message::class)
 
 /**
  * The [ClassName] of Protobuf [Any].
  */
-internal val AnyClass = ClassName(Any::class)
+public val AnyClass: ClassName = ClassName(Any::class)
 
 /**
  * The [ClassName] of [KnownTypes].
  */
-internal val KnownTypesClass = ClassName(KnownTypes::class)
+public val KnownTypesClass: ClassName = ClassName(KnownTypes::class)
 
 /**
  * The [ClassName] of [TypeUrl].
  */
-internal val TypeUrlClass = ClassName(TypeUrl::class)
+public val TypeUrlClass: ClassName = ClassName(TypeUrl::class)
 
 /**
  * The [ClassName] of [TypeName] from `java-base`.
  */
-internal val TypeNameClass = ClassName(TypeName::class)
+public val TypeNameClass: ClassName = ClassName(TypeName::class)
 
 /**
  * The [ClassName] of [java.lang.Integer].
  */
-internal val IntegerClass = ClassName(Integer::class)
+public val IntegerClass: ClassName = ClassName(Integer::class)
 
 /**
  * The [ClassName] of [java.lang.Long].
  */
-internal val LongClass = ClassName(java.lang.Long::class)
+public val LongClass: ClassName = ClassName(java.lang.Long::class)
 
 /**
  * The [ClassName] of [java.util.Objects].
  */
-internal val ObjectsClass = ClassName(Objects::class)
+public val ObjectsClass: ClassName = ClassName(Objects::class)
 
 /**
  * The [ClassName] of [Timestamps].
  */
-internal val TimestampsClass = ClassName(Timestamps::class)
+public val TimestampsClass: ClassName = ClassName(Timestamps::class)
 
 /**
  * The [ClassName] of [io.spine.base.Time].
  */
-internal val SpineTime = ClassName(Time::class)
+public val SpineTime: ClassName = ClassName(Time::class)

java/src/main/kotlin/io/spine/validation/java/violation/ConstraintViolations.kt → java-api/src/main/kotlin/io/spine/validation/api/expression/ConstraintViolations.kt

@@ -26,7 +26,7 @@
 
 @file:JvmName("ConstraintViolations")
 
-package io.spine.validation.java.violation
+package io.spine.validation.api.expression
 
 import io.spine.base.FieldPath
 import io.spine.protobuf.restoreProtobufEscapes
@@ -39,9 +39,6 @@ import io.spine.protodata.java.packToAny
 import io.spine.validate.ConstraintViolation
 import io.spine.validate.TemplateString
 import io.spine.validate.checkPlaceholdersHasValue
-import io.spine.validation.ErrorPlaceholder
-import io.spine.validation.java.expression.StringClass
-import io.spine.validation.java.expression.TemplateStringClass
 
 /**
  * Yields an expression that creates a new instance of [ConstraintViolation]
@@ -58,7 +55,7 @@ import io.spine.validation.java.expression.TemplateStringClass
  *   the invalid field value for this option is the field type's default value,
  *   which is treated as "no value" at all.
  */
-internal fun constraintViolation(
+public fun constraintViolation(
     errorMessage: Expression<TemplateString>,
     typeName: Expression<String>,
     fieldPath: Expression<FieldPath>?,
@@ -77,27 +74,25 @@ internal fun constraintViolation(
 }
 
 /**
- * Yields an expression that creates a new instance of [TemplateString]
- * with the given parameters.
+ * Yields an expression that creates a new instance of [TemplateString].
  *
- * @param template The template string that may have one or more placeholders.
  * @param placeholders The supported placeholders and their values.
  * @param optionName The name of the option, which declared the provided [placeholders].
  */
-internal fun templateString(
+public fun templateString(
     template: String,
-    placeholders: Map<ErrorPlaceholder, Expression<String>>,
+    placeholders: Map<String, Expression<String>>,
     optionName: String
 ): Expression<TemplateString> {
-    checkPlaceholdersHasValue(template, placeholders.mapKeys { it.key.value }) { missingKeys ->
+    checkPlaceholdersHasValue(template, placeholders) { missingKeys ->
         "Unexpected error message placeholders `$missingKeys` specified for the `($optionName)`" +
                 " option. The available placeholders: `${placeholders.keys}`. Please make sure" +
                 " that the policy that verifies the message placeholders and its code generator" +
                 " operate with the same set of placeholders."
     }
     val placeholderEntries = mapExpression(
         StringClass, StringClass,
-        placeholders.mapKeys { StringLiteral(it.key.toString()) }
+        placeholders.mapKeys { StringLiteral(it.key) }
     )
     val escapedTemplate = restoreProtobufEscapes(template)
     return TemplateStringClass.newBuilder()