mp.beanvalidation.adoc Maven / Gradle / Ivy
The newest version!
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2021, 2024 Oracle and/or its affiliates.
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
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= Bean Validation Introduction
:description: Bean Validation Introduction
:h1Prefix: MP
:pagename: bean-validation
:description: Bean Validation
:keywords: helidon, webserver, bean validation, validation
:feature-name: Bean Validation
:rootdir: {docdir}/..
include::{rootdir}/includes/mp.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
- <>
- <>
== Overview
Helidon supports Bean Validation via its integration with JAX-RS/Jersey. The
{jakarta-bean-validation-spec-url}[Jakarta Bean Validation specification] defines an API to validate Java beans.
Bean Validation is supported in REST resource classes as well as in regular application beans.
If bean validation is required outside JAX-RS/Jersey use cases, it is also available in Helidon.
It follows the standard {jakarta-bean-validation-spec-url}[Jakarta Bean Validation specification] which defines an API to validate Java beans.
include::{rootdir}/includes/dependencies.adoc[]
[source, xml]
----
org.glassfish.jersey.ext
jersey-bean-validation
----
For general validation, please add to your `pom.xml`:
[source, xml]
----
io.helidon.microprofile.bean-validation
helidon-microprofile-bean-validation
----
== API
The specification defines a small set of built-in constraints. Their usage is encouraged both in regular constraint declarations and as composing constraints. Using this set of constraints will enhance portability of your constraints across constraint-consuming frameworks relying on the metadata API (such as client side validation frameworks or database schema generation frameworks).
Built-in annotations are annotated with an empty `@Constraint` annotation to avoid any dependency between the specification API and a specific implementation. Each Jakarta Bean Validation provider must recognize built-in constraint annotations as valid constraint definitions and provide compliant constraint implementations for each. The built-in constraint validation implementation is having a lower priority than an XML mapping definition. In other words ConstraintValidator implementations for built-in constraints can be overridden by using the XML mapping (see Overriding constraint definitions in XML).
All built-in constraints are in the `jakarta.validation.constraints` package. Here is the list of constraints and their declaration.
[cols="2,5",role="flex, sm10"]
|===
|Annotation |Description
|`@Null`
|The annotated element must be `null`. Accepts any type.
|`@NotNull`
|The annotated element must not be `null`. Accepts any type.
|`@AssertTrue`
|The annotated element must be true. Supported types are `boolean` and `Boolean`. `Null` elements are considered valid.
|`@AssertFalse`
|The annotated element must be false. Supported types are `boolean` and `Boolean`. `Null` elements are considered valid.
|`@Min`
a|The annotated element must be a number whose value must be higher or equal to the specified minimum.
Supported types are:
* `BigDecimal`
* `BigInteger`
* `byte`, `short`, `int`, `long`, and their respective wrappers
Note that `double` and `float` are not supported due to rounding errors (some providers might provide some approximative support).
`Null` elements are considered valid.
|`@Max`
a|The annotated element must be a number whose value must be lower or equal to the specified maximum.
Supported types are:
* `BigDecimal`
* `BigInteger`
* `byte`, `short`, `int`, `long`, and their respective wrappers
Note that `double` and `float` are not supported due to rounding errors (some providers might provide some approximative support).
`Null` elements are considered valid.
|`@DecimalMin`
a|The annotated element must be a number whose value must be higher or equal to the specified minimum.
Supported types are:
* `BigDecimal`
* `BigInteger`
* `CharSequence`
* `byte`, `short`, `int`, `long`, and their respective wrappers
Note that `double` and `float` are not supported due to rounding errors (some providers might provide some approximative support).
`Null` elements are considered valid.
|`@DecimalMax`
a|The annotated element must be a number whose value must be lower or equal to the specified maximum.
Supported types are:
* `BigDecimal`
* `BigInteger`
* `CharSequence`
* `byte`, `short`, `int`, `long`, and their respective wrappers
Note that `double` and `float` are not supported due to rounding errors (some providers might provide some approximative support).
`Null` elements are considered valid.
|`@Negative`
a|The annotated element must be a strictly negative number (i.e. 0 is considered as an invalid value).
Supported types are:
* `BigDecimal`
* `BigInteger`
* `byte`, `short`, `int`, `long`, and their respective wrappers
`Null` elements are considered valid.
|`@NegativeOrZero`
a|The annotated element must be a negative number or 0.
Supported types are:
* `BigDecimal`
* `BigInteger`
* `byte`, `short`, `int`, `long`, `float`, or `double` and their respective wrappers
`Null` elements are considered valid.
|`@Positive`
a|The annotated element must be a strictly positive number (i.e. 0 is considered as an invalid value).
Supported types are:
* `BigDecimal`
* `BigInteger`
* `byte`, `short`, `int`, `long`, `float`, or `double` and their respective wrappers
`Null` elements are considered valid.
|`@PositiveOrZero`
a|The annotated element must be a positive number or 0.
Supported types are:
* `BigDecimal`
* `BigInteger`
* `byte`, `short`, `int`, `long`, `float`, or `double` and their respective wrappers
`Null` elements are considered valid.
|`@Size`
a|The annotated element size must be between the specified boundaries (included).
Supported types are:
* `CharSequence` - length of character sequence is evaluated
* `Collection` - collection size is evaluated
* `Map` - map size is evaluated
* `Array` (array length is evaluated)
`Null` elements are considered valid.
|`@Digits`
a|The annotated element must be a number within accepted range.
Supported types are:
* `BigDecimal`
* `BigInteger`
* `CharSequence`
* `byte`, `short`, `int`, `long`, and their respective wrapper types
`Null` elements are considered valid.
|`@Past`
a|The annotated element must be an instant, date or time in the past.
`Now` is defined by the `ClockProvider` attached to the `Validator` or `ValidatorFactory`. The default `clockProvider` defines the current time
according to the virtual machine, applying the current default time zone if needed.
Supported types are:
* `java.util.Date`
* `java.util.Calendar`
* `java.time.Instant`
* `java.time.LocalDate`
* `java.time.LocalDateTime`
* `java.time.LocalTime`
* `java.time.MonthDay`
* `java.time.OffsetDateTime`
* `java.time.OffsetTime`
* `java.time.Year`
* `java.time.YearMonth`
* `java.time.ZonedDateTime`
* `java.time.chrono.HijrahDate`
* `java.time.chrono.JapaneseDate`
* `java.time.chrono.MinguoDate`
* `java.time.chrono.ThaiBuddhistDate`
`Null` elements are considered valid.
|`@PastOrPresent`
a|The annotated element must be an instant, date or time in the past or in the present.
`Now` is defined by the `ClockProvider` attached to the `Validator` or `ValidatorFactory`. The default `clockProvider` defines the current time
according to the virtual machine, applying the current default time zone if needed.
The notion of present is defined relatively to the type on which the constraint is
used. For instance, if the constraint is on a `Year`, present would mean the whole
current year.
Supported types are:
* `java.util.Date`
* `java.util.Calendar`
* `java.time.Instant`
* `java.time.LocalDate`
* `java.time.LocalDateTime`
* `java.time.LocalTime`
* `java.time.MonthDay`
* `java.time.OffsetDateTime`
* `java.time.OffsetTime`
* `java.time.Year`
* `java.time.YearMonth`
* `java.time.ZonedDateTime`
* `java.time.chrono.HijrahDate`
* `java.time.chrono.JapaneseDate`
* `java.time.chrono.MinguoDate`
* `java.time.chrono.ThaiBuddhistDate`
`Null` elements are considered valid.
|`@Future`
a|The annotated element must be an instant, date or time in the future.
`Now` is defined by the `ClockProvider` attached to the `Validator` or `ValidatorFactory`. The default `clockProvider` defines the current time
according to the virtual machine, applying the current default time zone if needed.
Supported types are:
* `java.util.Date`
* `java.util.Calendar`
* `java.time.Instant`
* `java.time.LocalDate`
* `java.time.LocalDateTime`
* `java.time.LocalTime`
* `java.time.MonthDay`
* `java.time.OffsetDateTime`
* `java.time.OffsetTime`
* `java.time.Year`
* `java.time.YearMonth`
* `java.time.ZonedDateTime`
* `java.time.chrono.HijrahDate`
* `java.time.chrono.JapaneseDate`
* `java.time.chrono.MinguoDate`
* `java.time.chrono.ThaiBuddhistDate`
`Null` elements are considered valid.
|`@FutureOrPresent`
a|The annotated element must be an instant, date or time in the present or in the future.
`Now` is defined by the `ClockProvider` attached to the `Validator` or `ValidatorFactory`. The default `clockProvider` defines the current time
according to the virtual machine, applying the current default time zone if needed.
The notion of present here is defined relatively to the type on which the constraint is
used. For instance, if the constraint is on a `Year`, present would mean the whole
current year.
Supported types are:
* `java.util.Date`
* `java.util.Calendar`
* `java.time.Instant`
* `java.time.LocalDate`
* `java.time.LocalDateTime`
* `java.time.LocalTime`
* `java.time.MonthDay`
* `java.time.OffsetDateTime`
* `java.time.OffsetTime`
* `java.time.Year`
* `java.time.YearMonth`
* `java.time.ZonedDateTime`
* `java.time.chrono.HijrahDate`
* `java.time.chrono.JapaneseDate`
* `java.time.chrono.MinguoDate`
* `java.time.chrono.ThaiBuddhistDate`
`Null` elements are considered valid.
|`@Pattern`
a|The annotated `CharSequence` must match the specified regular expression.
The regular expression follows the Java regular expression conventions see `java.util.regex.Pattern`.
Accepts `CharSequence`.
`Null` elements are considered valid.
|`@NotEmpty`
a|The annotated element must not be `null` nor empty.
Supported types are:
* `CharSequence` - length of character sequence is evaluated
* `Collection` - collection size is evaluated
* `Map` - map size is evaluated
* `Array` (array length is evaluated)
|`@NotBlank`
a|The annotated element must not be `null` and must contain at least one
non-whitespace character. Accepts `CharSequence`.
|`@Email`
a| The string has to be a well-formed email address. Exact semantics of what makes up a valid
email address are left to Jakarta Bean Validation providers. Accepts `CharSequence`.
`Null` elements are considered valid.
|===
== Configuration
Bean Validation can be configured using `META-INF/validation.xml`.
For more information about configuring the validator factory in validation.xml, see link:https://docs.jboss.org/hibernate/stable/validator/reference/en-US/html_single/?v=7.0#chapter-xml-configuration[Hibernate Validator Documentation].
== Examples
1. The following example shows a simple resource method annotated with `@POST` whose
parameter must be _not null_ and _valid_. Validating a parameter in this case implies
making sure that any constraint annotations in the `Greeting` class are satisfied.
The resource method shall never be called if the validation fails, with a 400
(Bad Request) status code returned instead.
+
[source,java]
----
include::{sourcedir}/mp/BeanvalidationSnippets.java[tag=snippet_1, indent=0]
----
2. The following example shows a simple application with one field declared as _not null_ using `@NotNull` annotation:
+
[source,java]
----
include::{sourcedir}/mp/BeanvalidationSnippets.java[tag=snippet_2, indent=0]
----
+
If the bean contains a method parameter annotated with @Valid, and GreetingHolder with _null_greeting is passed, then a _ValidationException_ will be thrown:
+
[source,java]
----
include::{sourcedir}/mp/BeanvalidationSnippets.java[tag=snippet_3, indent=0]
----
+
NOTE: `beans.xml` is required to identify beans and for bean validation to work properly.
Examples are available in link:{helidon-github-examples-url}/microprofile/bean-validation[our official GitHub repository].
== Additional Information
Helidon uses link:https://hibernate.org/validator/[Hibernate Bean Validator] for general bean validation.
== Reference
* link:{jakarta-bean-validation-spec-url}[Bean Validation Specification]