0
# Dropwizard Validation
1

2
Dropwizard Validation provides comprehensive validation support for Dropwizard applications, extending beyond standard Jakarta Bean Validation (JSR-303) with custom validators and annotations. It includes specialized validators for Dropwizard-specific types such as Duration and DataSize ranges, port ranges, and value constraints, along with self-validation capabilities and advanced constraint violation handling.
3

4
## Package Information
5

6
- **Package Name**: dropwizard-validation
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Group ID**: io.dropwizard
10
- **Artifact ID**: dropwizard-validation
11
- **Installation**: Add to your Maven `pom.xml`:
12

13
```xml
14
<dependency>
15
    <groupId>io.dropwizard</groupId>
16
    <artifactId>dropwizard-validation</artifactId>
17
    <version>3.0.14</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import io.dropwizard.validation.*;
25
import io.dropwizard.validation.selfvalidating.*;
26
```
27

28
For specific validation annotations:
29

30
```java
31
import io.dropwizard.validation.DurationRange;
32
import io.dropwizard.validation.DataSizeRange;
33
import io.dropwizard.validation.OneOf;
34
import io.dropwizard.validation.PortRange;
35
import io.dropwizard.validation.Validated;
36
```
37

38
## Basic Usage
39

40
```java
41
import io.dropwizard.validation.*;
42
import io.dropwizard.util.Duration;
43
import io.dropwizard.util.DataSize;
44
import io.dropwizard.util.DataSizeUnit;
45
import javax.validation.constraints.NotNull;
46
import java.util.concurrent.TimeUnit;
47

48
public class ServerConfig {
49
    @NotNull
50
    @DurationRange(min = 1, max = 30, unit = TimeUnit.SECONDS)
51
    private Duration timeout;
52
    
53
    @DataSizeRange(min = 1, max = 1024, unit = DataSizeUnit.MEGABYTES)
54
    private DataSize maxFileSize;
55
    
56
    @PortRange(min = 8080, max = 9999)
57
    private int serverPort;
58
    
59
    @OneOf(value = {"development", "staging", "production"}, ignoreCase = true)
60
    private String environment;
61
    
62
    // getters and setters...
63
}
64

65
// Validate using standard Bean Validation
66
import javax.validation.Validator;
67
Validator validator = BaseValidator.newValidator();
68
Set<ConstraintViolation<ServerConfig>> violations = validator.validate(config);
69
```
70

71
## Architecture  
72

73
The validation framework is built on several key components:
74

75
- **Base Validation Utilities**: Core validator factory and constraint violation utilities
76
- **Duration Validators**: Validate Dropwizard Duration objects with time-based constraints
77
- **Data Size Validators**: Validate Dropwizard DataSize objects with size-based constraints  
78
- **Value Validators**: Validate string and numeric values against allowed sets or ranges
79
- **Self-Validation Framework**: Enable objects to define custom validation logic
80
- **Method Validation**: Validate method parameters and return values with custom annotations
81

82
This modular design integrates seamlessly with Dropwizard's configuration system and JAX-RS resource validation, providing both declarative annotation-based validation and programmatic validation capabilities.
83

84
## Capabilities
85

86
### Base Validation Utilities
87

88
Core utilities for creating validators and formatting constraint violations, providing the foundation for all validation operations in Dropwizard applications.
89

90
```java { .api }
91
public class BaseValidator {
92
    public static Validator newValidator();
93
    public static HibernateValidatorConfiguration newConfiguration();
94
}
95

96
public class ConstraintViolations {
97
    public static <T> String format(ConstraintViolation<T> v);
98
    public static <T> Collection<String> format(Set<ConstraintViolation<T>> violations);
99
    public static Collection<String> formatUntyped(Set<ConstraintViolation<?>> violations);
100
    public static <T> Set<ConstraintViolation<?>> copyOf(Set<ConstraintViolation<T>> violations);
101
}
102
```
103

104
[Base Validation Utilities](./base-validation.md)
105

106
### Duration Validation
107

108
Specialized validation annotations and validators for Dropwizard Duration objects, supporting minimum, maximum, and range constraints with configurable time units.
109

110
```java { .api }
111
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
112
@Retention(RUNTIME)
113
@Constraint(validatedBy = {})
114
public @interface DurationRange {
115
    long min() default 0;
116
    long max() default Long.MAX_VALUE;
117
    TimeUnit unit() default TimeUnit.SECONDS;
118
    String message() default "must be between {min} {unit} and {max} {unit}";
119
    Class<?>[] groups() default {};
120
    Class<? extends Payload>[] payload() default {};
121
}
122

123
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
124
@Retention(RUNTIME)
125
@Constraint(validatedBy = MinDurationValidator.class)
126
public @interface MinDuration {
127
    long value();
128
    TimeUnit unit() default TimeUnit.SECONDS;
129
    boolean inclusive() default true;
130
    String message() default "must be greater than ${inclusive == true ? 'or equal to ' : ''}{value} {unit}";
131
    Class<?>[] groups() default {};
132
    Class<? extends Payload>[] payload() default {};
133
}
134

135
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
136
@Retention(RUNTIME)
137
@Constraint(validatedBy = MaxDurationValidator.class)
138
public @interface MaxDuration {
139
    long value();
140
    TimeUnit unit() default TimeUnit.SECONDS;
141
    boolean inclusive() default true;
142
    String message() default "must be less than ${inclusive == true ? 'or equal to ' : ''}{value} {unit}";
143
    Class<?>[] groups() default {};
144
    Class<? extends Payload>[] payload() default {};
145
}
146
```
147

148
[Duration Validation](./duration-validation.md)
149

150
### Data Size Validation
151

152
Validation annotations and validators for Dropwizard DataSize objects, enabling constraints on file sizes, memory limits, and other size-based configurations.
153

154
```java { .api }
155
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
156
@Retention(RUNTIME)
157
@Constraint(validatedBy = {})
158
public @interface DataSizeRange {
159
    long min() default 0;
160
    long max() default Long.MAX_VALUE;
161
    DataSizeUnit unit() default DataSizeUnit.BYTES;
162
    String message() default "must be between {min} {unit} and {max} {unit}";
163
    Class<?>[] groups() default {};
164
    Class<? extends Payload>[] payload() default {};
165
}
166

167
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
168
@Retention(RUNTIME)
169
@Constraint(validatedBy = MinDataSizeValidator.class)
170
public @interface MinDataSize {
171
    long value();
172
    DataSizeUnit unit() default DataSizeUnit.BYTES;
173
    String message() default "must be greater than or equal to {value} {unit}";
174
    Class<?>[] groups() default {};
175
    Class<? extends Payload>[] payload() default {};
176
}
177

178
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
179
@Retention(RUNTIME)
180
@Constraint(validatedBy = MaxDataSizeValidator.class)
181
public @interface MaxDataSize {
182
    long value();
183
    DataSizeUnit unit() default DataSizeUnit.BYTES;
184
    String message() default "must be less than or equal to {value} {unit}";
185
    Class<?>[] groups() default {};
186
    Class<? extends Payload>[] payload() default {};
187
}
188
```
189

190
[Data Size Validation](./data-size-validation.md)
191

192
### Value Validation
193

194
Annotations for validating string values against allowed sets and numeric values against port ranges, with support for case-insensitive and whitespace-tolerant matching.
195

196
```java { .api }
197
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
198
@Retention(RUNTIME)
199
@Constraint(validatedBy = OneOfValidator.class)
200
public @interface OneOf {
201
    String[] value();
202
    boolean ignoreCase() default false;
203
    boolean ignoreWhitespace() default false;
204
    String message() default "must be one of {value}";
205
    Class<?>[] groups() default {};
206
    Class<? extends Payload>[] payload() default {};
207
}
208

209
@Target({METHOD, FIELD, ANNOTATION_TYPE, TYPE_USE})
210
@Retention(RUNTIME)
211
@Constraint(validatedBy = PortRangeValidator.class)
212
public @interface PortRange {
213
    int min() default 1;
214
    int max() default 65535;
215
    String message() default "{org.hibernate.validator.constraints.Range.message}";
216
    Class<?>[] groups() default {};
217
    Class<? extends Payload>[] payload() default {};
218
}
219
```
220

221
[Value Validation](./value-validation.md)
222

223
### Self-Validation Framework
224

225
A framework enabling objects to define custom validation logic through annotated methods, providing flexibility for complex business rules that cannot be expressed with standard validation annotations.
226

227
```java { .api }
228
@Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
229
@Retention(RetentionPolicy.RUNTIME)
230
@Constraint(validatedBy = SelfValidatingValidator.class)
231
public @interface SelfValidating {
232
    String message() default "";
233
    Class<?>[] groups() default {};
234
    Class<? extends Payload>[] payload() default {};
235
}
236

237
@Target(ElementType.METHOD)
238
@Retention(RetentionPolicy.RUNTIME)
239
public @interface SelfValidation {
240
}
241

242
public class ViolationCollector {
243
    public void addViolation(String message);
244
    public void addViolation(String message, Map<String, Object> messageParameters);
245
    public void addViolation(String propertyName, String message);
246
    public void addViolation(String propertyName, String message, Map<String, Object> messageParameters);
247
    public void addViolation(String propertyName, Integer index, String message);
248
    public void addViolation(String propertyName, Integer index, String message, Map<String, Object> messageParameters);
249
    public void addViolation(String propertyName, String key, String message);
250
    public void addViolation(String propertyName, String key, String message, Map<String, Object> messageParameters);
251
    public boolean hasViolationOccurred();
252
    public void setViolationOccurred(boolean violationOccurred);
253
    public ConstraintValidatorContext getContext();
254
}
255
```
256

257
[Self-Validation Framework](./self-validation.md)
258

259
### Method Validation
260

261
Annotations and utilities for validating method parameters and enabling bean predicate validation, supporting advanced validation scenarios beyond field-level constraints.
262

263
```java { .api }
264
@Target({PARAMETER, METHOD})
265
@Retention(RUNTIME)
266
public @interface Validated {
267
    Class<?>[] value() default {Default.class};
268
}
269

270
@Target({TYPE, ANNOTATION_TYPE, METHOD})
271
@Retention(RUNTIME)
272
@Constraint(validatedBy = MethodValidator.class)
273
public @interface ValidationMethod {
274
    String message() default "is not valid";
275
    Class<?>[] groups() default {};
276
    Class<? extends Payload>[] payload() default {};
277
}
278
```
279

280
[Method Validation](./method-validation.md)
281

282
## Types
283

284
```java { .api }
285
// Core utility classes are part of the base validation capability
286
// Value extractors and interpolation helpers support the validation framework
287
// All validator implementations are internal and not part of the public API
288
```