0
# Data Size Validation
1

2
Validation annotations and validators for Dropwizard DataSize objects, enabling constraints on file sizes, memory limits, and other size-based configurations. These annotations work specifically with `io.dropwizard.util.DataSize` instances and support all standard data size units.
3

4
## Capabilities
5

6
### Data Size Range Validation
7

8
Validates that a DataSize falls within a specified range, combining minimum and maximum constraints.
9

10
```java { .api }
11
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
12
@Retention(RUNTIME)
13
@Constraint(validatedBy = {})
14
@MinDataSize(0)
15
@MaxDataSize(value = Long.MAX_VALUE, unit = DataSizeUnit.PEBIBYTES)
16
@ReportAsSingleViolation
17
public @interface DataSizeRange {
18
    /**
19
     * The minimum value of the range the validated DataSize must be in.
20
     *
21
     * @return the minimum value
22
     */
23
    long min() default 0;
24

25
    /**
26
     * The maximum value of the range the validated DataSize must be in.
27
     *
28
     * @return the maximum value
29
     */
30
    long max() default Long.MAX_VALUE;
31

32
    /**
33
     * The unit of the validated range.
34
     *
35
     * @return the DataSizeUnit
36
     */
37
    DataSizeUnit unit() default DataSizeUnit.BYTES;
38

39
    /**
40
     * The validation message for this constraint.
41
     *
42
     * @return the message
43
     */
44
    String message() default "must be between {min} {unit} and {max} {unit}";
45

46
    /**
47
     * The groups the constraint belongs to.
48
     *
49
     * @return an array of classes representing the groups
50
     */
51
    Class<?>[] groups() default {};
52

53
    /**
54
     * The payloads of this constraint.
55
     *
56
     * @return the array of payload classes
57
     */
58
    Class<? extends Payload>[] payload() default {};
59

60
    /**
61
     * Defines several @DataSizeRange annotations on the same element.
62
     */
63
    @Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
64
    @Retention(RUNTIME)
65
    @Documented
66
    @interface List {
67
        DataSizeRange[] value();
68
    }
69
}
70
```
71

72
**Usage Example:**
73

74
```java
75
import io.dropwizard.validation.DataSizeRange;
76
import io.dropwizard.util.DataSize;
77
import io.dropwizard.util.DataSizeUnit;
78

79
public class FileUploadConfig {
80
    // Upload size between 1KB and 10MB
81
    @DataSizeRange(min = 1, max = 10, unit = DataSizeUnit.MEGABYTES)
82
    private DataSize maxUploadSize;
83
    
84
    // Memory buffer between 512 bytes and 64KB
85
    @DataSizeRange(min = 512, max = 64, unit = DataSizeUnit.KILOBYTES)
86
    private DataSize bufferSize;
87
    
88
    // Cache size between 1MB and 1GB
89
    @DataSizeRange(min = 1, max = 1024, unit = DataSizeUnit.MEGABYTES)
90
    private DataSize cacheSize;
91
}
92
```
93

94
### Minimum Data Size Validation
95

96
Validates that a DataSize meets or exceeds a minimum threshold.
97

98
```java { .api }
99
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
100
@Retention(RUNTIME)
101
@Constraint(validatedBy = MinDataSizeValidator.class)
102
public @interface MinDataSize {
103
    /**
104
     * The annotation's value.
105
     *
106
     * @return value the element must be higher or equal to
107
     */
108
    long value();
109

110
    /**
111
     * The unit of the annotation.
112
     *
113
     * @return unit of the value the element must be higher or equal to
114
     */
115
    DataSizeUnit unit() default DataSizeUnit.BYTES;
116

117
    /**
118
     * The validation message for this constraint.
119
     *
120
     * @return the message
121
     */
122
    String message() default "must be greater than or equal to {value} {unit}";
123

124
    /**
125
     * The groups the constraint belongs to.
126
     *
127
     * @return an array of classes representing the groups
128
     */
129
    Class<?>[] groups() default {};
130

131
    /**
132
     * The payloads of this constraint.
133
     *
134
     * @return the array of payload classes
135
     */
136
    Class<? extends Payload>[] payload() default {};
137
}
138
```
139

140
**Usage Example:**
141

142
```java
143
import io.dropwizard.validation.MinDataSize;
144
import io.dropwizard.util.DataSize;
145
import io.dropwizard.util.DataSizeUnit;
146

147
public class StorageConfig {
148
    // Minimum disk space requirement
149
    @MinDataSize(value = 100, unit = DataSizeUnit.MEGABYTES)
150
    private DataSize minDiskSpace;
151
    
152
    // Memory pool must be at least 32MB
153
    @MinDataSize(value = 32, unit = DataSizeUnit.MEGABYTES)
154
    private DataSize memoryPoolSize;
155
    
156
    // Log file size must be at least 1KB
157
    @MinDataSize(value = 1024, unit = DataSizeUnit.BYTES)
158
    private DataSize minLogFileSize;
159
}
160
```
161

162
### Maximum Data Size Validation
163

164
Validates that a DataSize does not exceed a maximum threshold.
165

166
```java { .api }
167
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
168
@Retention(RUNTIME)
169
@Constraint(validatedBy = MaxDataSizeValidator.class)
170
public @interface MaxDataSize {
171
    /**
172
     * The annotation's value.
173
     *
174
     * @return value the element must be less than or equal to
175
     */
176
    long value();
177

178
    /**
179
     * The unit of the annotation.
180
     *
181
     * @return unit of the value the element must be less than or equal to
182
     */
183
    DataSizeUnit unit() default DataSizeUnit.BYTES;
184

185
    /**
186
     * The validation message for this constraint.
187
     *
188
     * @return the message
189
     */
190
    String message() default "must be less than or equal to {value} {unit}";
191

192
    /**
193
     * The groups the constraint belongs to.
194
     *
195
     * @return an array of classes representing the groups
196
     */
197
    Class<?>[] groups() default {};
198

199
    /**
200
     * The payloads of this constraint.
201
     *
202
     * @return the array of payload classes
203
     */
204
    Class<? extends Payload>[] payload() default {};
205
}
206
```
207

208
**Usage Example:**
209

210
```java
211
import io.dropwizard.validation.MaxDataSize;
212
import io.dropwizard.util.DataSize;
213
import io.dropwizard.util.DataSizeUnit;
214

215
public class LimitConfig {
216
    // Maximum file size for processing
217
    @MaxDataSize(value = 500, unit = DataSizeUnit.MEGABYTES)
218
    private DataSize maxFileSize;
219
    
220
    // Heap size cannot exceed 2GB
221
    @MaxDataSize(value = 2, unit = DataSizeUnit.GIGABYTES)
222
    private DataSize maxHeapSize;
223
    
224
    // Request body size limit
225
    @MaxDataSize(value = 10, unit = DataSizeUnit.MEGABYTES)
226
    private DataSize maxRequestSize;
227
}
228
```
229

230
## Advanced Usage
231

232
### Combining Multiple Data Size Constraints
233

234
```java
235
import io.dropwizard.validation.*;
236
import io.dropwizard.util.DataSize;
237
import io.dropwizard.util.DataSizeUnit;
238

239
public class AdvancedDataConfig {
240
    // Multiple constraints on the same field
241
    @MinDataSize(value = 1, unit = DataSizeUnit.MEGABYTES)
242
    @MaxDataSize(value = 100, unit = DataSizeUnit.MEGABYTES)
243
    private DataSize workingMemory;
244
    
245
    // Using DataSizeRange is equivalent and more concise
246
    @DataSizeRange(min = 1, max = 100, unit = DataSizeUnit.MEGABYTES)
247
    private DataSize alternativeMemory;
248
    
249
    // Complex validation with custom message
250
    @DataSizeRange(
251
        min = 512, 
252
        max = 65536, 
253
        unit = DataSizeUnit.BYTES,
254
        message = "Buffer size must be between 512 bytes and 64KB"
255
    )
256
    private DataSize bufferSize;
257
}
258
```
259

260
### Working with Different Data Size Units
261

262
```java
263
import io.dropwizard.validation.DataSizeRange;
264
import io.dropwizard.util.DataSize;
265
import io.dropwizard.util.DataSizeUnit;
266

267
public class MultiscaleConfig {
268
    // Small values in bytes
269
    @DataSizeRange(min = 1024, max = 65536, unit = DataSizeUnit.BYTES)
270
    private DataSize packetSize;
271
    
272
    // Medium values in kilobytes
273
    @DataSizeRange(min = 1, max = 1024, unit = DataSizeUnit.KILOBYTES)
274
    private DataSize cacheLineSize;
275
    
276
    // Large values in megabytes
277
    @DataSizeRange(min = 1, max = 512, unit = DataSizeUnit.MEGABYTES)
278
    private DataSize heapSize;
279
    
280
    // Very large values in gigabytes
281
    @DataSizeRange(min = 1, max = 100, unit = DataSizeUnit.GIGABYTES)
282
    private DataSize diskSpace;
283
}
284
```
285

286
### Validation Groups for Different Environments
287

288
```java
289
import io.dropwizard.validation.DataSizeRange;
290
import io.dropwizard.util.DataSize;
291
import io.dropwizard.util.DataSizeUnit;
292

293
public interface Development {}
294
public interface Production {}
295

296
public class EnvironmentDataConfig {
297
    // Different size limits for different environments
298
    @DataSizeRange(min = 1, max = 10, unit = DataSizeUnit.MEGABYTES, groups = Development.class)
299
    @DataSizeRange(min = 100, max = 1000, unit = DataSizeUnit.MEGABYTES, groups = Production.class)
300
    private DataSize databaseConnectionPool;
301
}
302

303
// Validate with specific group
304
Validator validator = BaseValidator.newValidator();
305
Set<ConstraintViolation<EnvironmentDataConfig>> violations = 
306
    validator.validate(config, Production.class);
307
```
308

309
## Supported Data Size Units
310

311
The following `DataSizeUnit` values are supported:
312

313
- `BYTES` - Basic byte unit
314
- `KILOBYTES` - 1,000 bytes (decimal)
315
- `MEGABYTES` - 1,000,000 bytes (decimal)
316
- `GIGABYTES` - 1,000,000,000 bytes (decimal)
317
- `TERABYTES` - 1,000,000,000,000 bytes (decimal)
318
- `PETABYTES` - 1,000,000,000,000,000 bytes (decimal)
319
- `KIBIBYTES` - 1,024 bytes (binary)
320
- `MEBIBYTES` - 1,048,576 bytes (binary)
321
- `GIBIBYTES` - 1,073,741,824 bytes (binary)
322
- `TEBIBYTES` - 1,099,511,627,776 bytes (binary)
323
- `PEBIBYTES` - 1,125,899,906,842,624 bytes (binary)
324

325
## Integration Notes
326

327
- All data size validators work exclusively with `io.dropwizard.util.DataSize` objects
328
- `null` values are considered valid (use `@NotNull` to reject null values)
329
- Validators handle both decimal (KB, MB, GB) and binary (KiB, MiB, GiB) units
330
- Data size constraints integrate seamlessly with Dropwizard configuration validation
331
- Use `@DataSizeRange` for most cases; use individual `@MinDataSize`/`@MaxDataSize` when you need different units or validation messages