XJC Plugin to generate Bean Validation Annotations 2.0 (JSR-380)
This project defines 2 XJC and 1 CXF plugins:
-
Jsr308Annotations
a XJC plugin that adds Bean Validation 2.0 or JSR 380 validations suporting bothjavax
orjakarta
packages -
ReplacePrimitives
a XJC plugin that replaces the generated primitives with the corresponding boxed types (i.e.int
->Integer
) -
an Apache Cxf plugin that adds the
javax
orjakarta
@Valid
annotation to the SOAP methods and their parameters (both optionally) of the generated Port Type interface. This plugin is configured using the sameJSR308Annotations
name.
There are 2 example projects containing many different plugins and configurations available for reference (each new version of this plugin is tested against these two progects):
-
GitHub - fillumina/krasa-jaxb-tools-jdk21-example: Examples of usage of krasa-jaxb-tools using latest technologies (Java 21) as the name suggests it's compiled with JDK 21 and provides working examples of many different plugins using both XJC and CXF configured with both
javax
andjakarta
packages using the latest versions available. -
GitHub - fillumina/krasa-jaxb-tools-example: Sample project for https://github.com/fillumina/krasa-jaxb-tools uses JDK 8 and provides examples using the latest versions of plugins and dependencies available for that java version.
The project is bounded to support Java 8 (JDK 1.8) because of some old projects still requiring it. All dependencies are selected from the latest available versions still supporting that.
-
2.3.6
various fixes and improvements:-
allow numeric annotations to String generated values
-
fix invalid multiple pattern generation with inherited restrictions
-
all tests are now performed automatically against both
javax
andjakarta
packages -
fix for
javax
packages being generated by the CXF plugin even whenjakarta
was required (ValidSEIGenerator plugin) -
reorganization of test packages to improve readability
-
-
2.3.5
fix critical vulnerabilities found in dependencies, see Sonatype report. -
2.3.4
bug fix release:- fix Issue #17 where
@DecimalMin
and@DecimalMax
superfluous annotations were added to numeric java types. A new argument has been createdgenerateAllNumericConstraints
in case all constraints would be needed (even superflous ones).
- fix Issue #17 where
-
2.3.3
bug fix release:- fix Issue #13 where it's been wrongly assumed that:
SimpleTypeImpl particle = (SimpleTypeImpl) definition
was always true. A check has beed added to prevent theClassCastException
.
- fix Issue #13 where it's been wrongly assumed that:
-
2.3.2
another bug fix release:- fix
@Pattern
added to wrong fields (regression from 2.2) - add
@EachPattern
when needed forList<String>
fields - rename
generateStringListAnnotations
option togenerateListAnnotations
because it is not limited to list of strings - disable
generateListAnnotations
by default (was enabled)
- fix
-
2.3.1
bug fix release:@Valid
annotation was not added by default- remove
singlePattern
option because@Pattern.List
is not semantically correct - disable
jpa
option because not really useful - disable
JSR_349
option it was referring to Validation API 1.1 while now we use 2.0 - add a lot of tests to establish a solid baseline (defaults was backported and tested on 2.2)
-
2.3
A huge refactoring and bug fixing:- added
singlePattern
option - fixed
generateServiceValidationAnnotations
used byValidSEIGenerator
to accept string parameter - dependencies updated to the latest version still supporting JDK 1.8
- a maven rule has been set to force compilation with JDK 1.8
- added
-
2.2
Some new features added because of PR requests- Added
@Valid
annotation tosequence
s to force items validation - Added support for
Jakarta EE 9
with parametervalidationAnnotations
- Added
-
2.1
Revert back to Java 1.8 (sorry folks!). -
2.0
A refactorized version of the original krasa-jaxb-toos last synced on August 2022, with some enhancements (support forEachDigits
,EachDecimalMin
andEachDecimalMax
in primitive lists), improved tests and bug fixed. It is compiled using JDK 11. Thepom.xml
groupId
has been changed tocom.fillumina
.
<dependency>
<groupId>com.fillumina</groupId>
<artifactId>krasa-jaxb-tools</artifactId>
<version>2.3.6</version>
</dependency>
verbose
(boolean, default=false
) print verbose messages to output example:-XJsr303Annotations:verbose=true
validationAnnotations
(javax
|jakarta
, default=javax
): selects the library to use for validation annotations example:-XJsr303Annotations:validationAnnotations=javax
targetNamespace
(string): adds @Valid annotation only if the element has the given namespace example:-XJsr303Annotations:targetNamespace=a
generateNotNullAnnotations
(boolean, default=true
): adds a@NotNull
annotation if an element hasminOccours
not 0, isrequired
or is notnillable
. examples:-XJsr303Annotations:generateNotNullAnnotations=true
notNullAnnotationsCustomMessages
(boolean or string, default=false
): values aretrue
,FieldName
,ClassName
, or an actual message (see further explanation in a note down below) example:-XJsr303Annotations:notNullAnnotationsCustomMessages=ClassName
generateListAnnotations
(boolean, optional, defaultfalse
) generates validator-collection annotations annotations example:-XJsr303Annotations:generateListAnnotations=true
generateServiceValidationAnnotations
(string, accepts:in
,out
,inout
, works withapache-cxf
only) adds@Valid
annotations to respective message direction (in, out or both). example:-XJsr303Annotations:generateServiceValidationAnnotations=inout
generateAllNumericConstraints
(boolean, defaults tofalse
) generates all@DecimalMin
and@DecimalMax
even those regarding the natural boudaries of the referred java type. example:-XJsr303Annotations:generateAllNumericConstraints=true
-
Arguments accepting booleans can either be given the value
true
as withverbose=true
or simply be left without a value at all and that will be interpteted as beingtrue
(you can omit the=
too). -
All arguments are optional.
@NotNull
default validation message is not always helpful, so it can be customized with -XJsr303Annotations:notNullAnnotationsCustomMessages=OPTION where OPTION is one of the following:
false
default: no custom messagetrue
message is present but equivalent to the default: "{javax.validation.constraints.NotNull.message}"FieldName
field name is prefixed to the default message: "fieldName {javax.validation.constraints.NotNull.message}"ClassName
class and field name are prefixed to the default message: "ClassName.fieldName {javax.validation.constraints.NotNull.message}"other-non-empty-text
arbitrary message, with substitutable, case-sensitive parameters{ClassName}
and{FieldName}
, i.e.: "Class {ClassName} field {FieldName} non-null"
Bean validation policy can be customized with -XJsr303Annotations:generateServiceValidationAnnotations=OPTION
where OPTION is one of the following (the option is case insensitive):
InOut
(default: validate requests and responses)In
(validate only requests)Out
(validate only responses)
Using this option requires to specify krasa
as front end generator in the CXF plugin with the option -frontend krasa
(See example in krasa-jaxb-tools-example/krasa-cxf-codegen-plugin-example/pom.xml at master · fillumina/krasa-jaxb-tools-example · GitHub )
That is a different plugin within this same packakge that can be enabled with the option -XReplacePrimitives
. It replaces primitive types with boxed ones (int
-> Integer
). It's enabled in the krasa-cxf-codegen-plugin-example project as an example.
WARNING: must be defined before XhashCode or Xequals.
The plugin generates sources annotated with the following Java Bean Validation 2.0 (JSR 380) annotations (with either javax
or jakarta
packages depending on the configuration, see -XJsr303Annotations:validationAnnotations=javax
):
@Valid
annotation for all complex types, can be further restricted to generate only for types from defined schema:-XJsr303Annotations:targetNamespace=http://www.foo.com/bar
@NotNull
annotation for objects that has a MinOccur value >= 1 or for required attributes@Size
for lists that have minOccurs > 1@Size
if there is a maxLength or minLength or length restriction@DecimalMax
for maxInclusive restriction@DecimalMin
for minInclusive restriction@DecimalMax
for maxExclusive restriction, enable new parameter (inclusive=false) with: -XJsr303Annotations:JSR_349=true@DecimalMin
for minExclusive restriction, enable new parameter (inclusive=false) with: -XJsr303Annotations:JSR_349=true@Digits
if there is a totalDigits or fractionDigits restriction.@Pattern
and@PatternList
if there is a Pattern restriction (seesinglePattern
option)
Any issue or bug fix reported is extremely welcome but to help me understand the problem and reduce the time to publish the fix I kindly ask to comply to these roles:
-
Issues should contain a detailed description and an example to show how and when the code is failing. It might be a failing test or a simple github project.
-
Fixes should contain a test that proves the solution to the problem (and the test should be present in a previous commit to the fix to show that it fails). It is appreciated that the solution contains as little refactoring as possible and is focused only on fixing one issue. Each fix should focus on one specific issue.
- change the plugin name to
Jsr380Annotations
because it's now about the Java Specification Request 380. Being a breaking change it should cause the version to jump to 2.4.