Skip to content

armgit / core

Public Imported from GitHub
0

100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps

Document value constraint descriptions (#1725)

Ekhorne3db1a7ffb02
diff --git a/model/src/main/java/org/openremote/model/value/ValueConstraint.java b/model/src/main/java/org/openremote/model/value/ValueConstraint.java
index e9b469880..dcbfa32c5 100644
--- a/model/src/main/java/org/openremote/model/value/ValueConstraint.java
+++ b/model/src/main/java/org/openremote/model/value/ValueConstraint.java
@@ -20,6 +20,7 @@
package org.openremote.model.value;
import com.fasterxml.jackson.annotation.*;
+import com.kjetland.jackson.jsonSchema.annotations.JsonSchemaDescription;
import org.openremote.model.util.ValueUtil;
import java.io.Serializable;
@@ -36,7 +37,7 @@ import java.util.regex.PatternSyntaxException;
// https://github.com/java-json-tools/json-schema-validator which is no longer maintained) or find a JSR-380
// implementation that supports dynamic validators
/**
- * Represents a constraint to apply to a value; these are based on JSR-380 validation.
+ * Represents a constraint to apply to a value; most are based on JSR-380 validation.
*/
@JsonTypeInfo(property = "type", use = JsonTypeInfo.Id.NAME)
@JsonSubTypes({
@@ -53,6 +54,7 @@ import java.util.regex.PatternSyntaxException;
@JsonSubTypes.Type(ValueConstraint.NotBlank.class),
@JsonSubTypes.Type(ValueConstraint.NotNull.class)
})
+@JsonSchemaDescription("The constraints must be a JSON compatible list of objects.")
public abstract class ValueConstraint implements Serializable {
public static final String VALUE_CONSTRAINT_INVALID = "{ValueConstraint.Invalid}";
@@ -69,7 +71,13 @@ public abstract class ValueConstraint implements Serializable {
public static final String NOT_BLANK_MESSAGE_TEMPLATE = "{ValueConstraint.NotBlank.message}";
public static final String NOT_NULL_MESSAGE_TEMPLATE = "{ValueConstraint.NotNull.message}";
+ /**
+ * The attribute value must be between the specified boundaries based on the {@link #min} and
+ * {@link #max} properties. Supported types are JSON compatible strings, arrays and objects. Null values
+ * are considered valid.
+ */
@JsonTypeName("size")
+ @JsonSchemaDescription("The attribute value must be between the specified boundaries based on the `min` and `max` properties. Supported types are JSON compatible strings, arrays and objects. Null values are considered valid.")
public static class Size extends ValueConstraint {
protected Integer min;
@@ -129,7 +137,12 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must be a number higher or equal to the specified value on the {@link #min}
+ * property. Null values are considered valid.
+ */
@JsonTypeName("min")
+ @JsonSchemaDescription("The attribute value must be a number higher or equal to the specified value on the `min` property. Null values are considered valid.")
public static class Min extends ValueConstraint {
protected Number min;
@@ -205,7 +218,12 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must be a number lower or equal to the specified value on the {@link #max}
+ * property. Null values are considered valid.
+ */
@JsonTypeName("max")
+ @JsonSchemaDescription("The attribute value must be a number lower or equal to the specified value on the `max` property. Null values are considered valid.")
public static class Max extends ValueConstraint {
protected Number max;
@@ -281,7 +299,14 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must match the regular expression pattern described in the {@link #regexp}
+ * property. The regular expression follows the Java regular expression conventions. Flags can be
+ * specified using the {@link #flags} property with values: CASE_INSENSITIVE, MULTILINE, DOTALL,
+ * UNIX_LINES, UNICODE_CASE, CANON_EQ and COMMENTS. Null values are considered valid.
+ */
@JsonTypeName("pattern")
+ @JsonSchemaDescription("The attribute value must match the regular expression pattern described in the `regexp` property. The regular expression follows the Java regular expression conventions. Flags can be specified using the `flags` property with values: CASE_INSENSITIVE, MULTILINE, DOTALL, UNIX_LINES, UNICODE_CASE, CANON_EQ and COMMENTS. Null values are considered valid.")
public static class Pattern extends ValueConstraint {
private static final java.util.regex.Pattern ESCAPE_MESSAGE_PARAMETER_PATTERN = java.util.regex.Pattern.compile("([\\\\{}$])");
protected String regexp;
@@ -346,7 +371,17 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must match any of the specified values in the {@link #allowedValues} property. The
+ * associated input in the UI will change to a select input with the options specified in the
+ * {@link #allowedValues} property. The {@link #allowedValueNames} property accepts a list of names that
+ * replace the labels in the select input, if the {@link #allowedValueNames} list matches the length of
+ * the {@link #allowedValues} list otherwise it falls back to the {@link #allowedValues} as labels. Null
+ * values are considered valid. If {@link #allowedValues} is not specified or empty the constraint only
+ * accepts null values.
+ */
@JsonTypeName("allowedValues")
+ @JsonSchemaDescription("The attribute value must match any of the specified values in the `allowedValues` property. The associated input in the UI will change to a select input with the options specified in the `allowedValues` property. The `allowedValueNames` property accepts a list of names that replace the labels in the select input, if the `allowedValueNames` list matches the length of the `allowedValues` list otherwise it falls back to the `allowedValues` as labels. Null values are considered valid. If `allowedValues` is not specified or empty the constraint only accepts null values.")
public static class AllowedValues extends ValueConstraint {
Object[] allowedValues;
String[] allowedValueNames;
@@ -406,7 +441,13 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must be a java time object, java date object, a string in ISO8601 format or a
+ * number representing epoch milliseconds; the value must represent a time in the past. Null values are
+ * considered valid.
+ */
@JsonTypeName("past")
+ @JsonSchemaDescription("The attribute value must be a java time object, java date object, a string in ISO8601 format or a number representing epoch milliseconds; the value must represent a time in the past. Null values are considered valid.")
public static class Past extends ValueConstraint {
public Past() {
@@ -440,7 +481,13 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must be a java time object, java date object, a string in ISO8601 format or a
+ * number representing epoch milliseconds; the value must represent a time in the past or present. Null
+ * values are considered valid.
+ */
@JsonTypeName("pastOrPresent")
+ @JsonSchemaDescription("The attribute value must be a java time object, java date object, a string in ISO8601 format or a number representing epoch milliseconds; the value must represent a time in the past or present. Null values are considered valid.")
public static class PastOrPresent extends ValueConstraint {
public PastOrPresent() {
@@ -474,7 +521,13 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must be a java time object, java date object, a string in ISO8601 format or a
+ * number representing epoch milliseconds; the value must represent a time in the future. Null values are
+ * considered valid.
+ */
@JsonTypeName("future")
+ @JsonSchemaDescription("The attribute value must be a java time object, java date object, a string in ISO8601 format or a number representing epoch milliseconds; the value must represent a time in the future. Null values are considered valid.")
public static class Future extends ValueConstraint {
public Future() {
@@ -508,7 +561,13 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must be a java time object, java date object, a string in ISO8601 format or a
+ * number representing epoch milliseconds; the value must represent a time in the future or present. Null
+ * values are considered valid.
+ */
@JsonTypeName("futureOrPresent")
+ @JsonSchemaDescription("The attribute value must be a java time object, java date object, a string in ISO8601 format or a number representing epoch milliseconds; the value must represent a time in the future or present. Null values are considered valid.")
public static class FutureOrPresent extends ValueConstraint {
public FutureOrPresent() {
@@ -542,7 +601,12 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must not be null nor empty. Supported types are JSON compatible strings, arrays
+ * and objects which contain at least 1 character, item or property.
+ */
@JsonTypeName("notEmpty")
+ @JsonSchemaDescription("The attribute value must not be null nor empty. Supported types are JSON compatible strings, arrays and objects which contain at least 1 character, item or property.")
public static class NotEmpty extends ValueConstraint {
public NotEmpty() {
@@ -586,7 +650,12 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must not be null and must contain at least 1 non-whitespace character. Accepts
+ * strings.
+ */
@JsonTypeName("notBlank")
+ @JsonSchemaDescription("The attribute value must not be null and must contain at least 1 non-whitespace character. Accepts strings.")
public static class NotBlank extends ValueConstraint {
public NotBlank() {
super(NOT_BLANK_MESSAGE_TEMPLATE);
@@ -613,7 +682,11 @@ public abstract class ValueConstraint implements Serializable {
}
}
+ /**
+ * The attribute value must not be null. Accepts any type.
+ */
@JsonTypeName("notNull")
+ @JsonSchemaDescription("The attribute value must not be null. Accepts any type.")
public static class NotNull extends ValueConstraint {
public NotNull() {