0
# Value Validation
1

2
Annotations for validating string values against allowed sets and numeric values against port ranges, with support for case-insensitive and whitespace-tolerant matching. These validators provide flexible constraints for common validation scenarios.
3

4
## Capabilities
5

6
### One Of Validation
7

8
Validates that an object's string representation is one of a predefined set of allowed values, with optional case and whitespace handling. Works with any object type by converting it to string.
9

10
```java { .api }
11
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
12
@Retention(RUNTIME)
13
@Constraint(validatedBy = OneOfValidator.class)
14
public @interface OneOf {
15
    /**
16
     * The set of valid values.
17
     *
18
     * @return an array containing the valid string values
19
     */
20
    String[] value();
21

22
    /**
23
     * Whether to ignore case.
24
     *
25
     * @return if the case should be ignored
26
     */
27
    boolean ignoreCase() default false;
28

29
    /**
30
     * Whether to ignore leading and trailing whitespace.
31
     *
32
     * @return if leading and trailing whitespaces should be ignored
33
     */
34
    boolean ignoreWhitespace() default false;
35

36
    /**
37
     * The validation message for this constraint.
38
     *
39
     * @return the message
40
     */
41
    String message() default "must be one of {value}";
42

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

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

59
**Usage Examples:**
60

61
```java
62
import io.dropwizard.validation.OneOf;
63

64
public class ApplicationConfig {
65
    // Basic enum-like validation
66
    @OneOf({"development", "staging", "production"})
67
    private String environment;
68
    
69
    // Case-insensitive matching
70
    @OneOf(value = {"GET", "POST", "PUT", "DELETE"}, ignoreCase = true)
71
    private String httpMethod;
72
    
73
    // Ignore whitespace and case
74
    @OneOf(
75
        value = {"debug", "info", "warn", "error"}, 
76
        ignoreCase = true, 
77
        ignoreWhitespace = true
78
    )
79
    private String logLevel;
80
    
81
    // Custom error message
82
    @OneOf(
83
        value = {"mysql", "postgresql", "h2"}, 
84
        message = "Database type must be one of: mysql, postgresql, h2"
85
    )
86
    private String databaseType;
87
}
88
```
89

90
### Port Range Validation
91

92
Validates that an integer value represents a valid port number within a specified range, with special handling for port 0 (dynamic allocation).
93

94
```java { .api }
95
@Target({METHOD, FIELD, ANNOTATION_TYPE, TYPE_USE})
96
@Retention(RUNTIME)
97
@Constraint(validatedBy = PortRangeValidator.class)
98
public @interface PortRange {
99
    /**
100
     * The minimum value of the port range the validated int must be in.
101
     *
102
     * @return the minimum value
103
     */
104
    int min() default 1;
105

106
    /**
107
     * The maximum value of the port range the validated int must be in.
108
     *
109
     * @return the maximum value
110
     */
111
    int max() default 65535;
112

113
    /**
114
     * The validation message for this constraint.
115
     *
116
     * @return the message
117
     */
118
    String message() default "{org.hibernate.validator.constraints.Range.message}";
119

120
    /**
121
     * The groups the constraint belongs to.
122
     *
123
     * @return an array of classes representing the groups
124
     */
125
    Class<?>[] groups() default {};
126

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

136
**Usage Examples:**
137

138
```java
139
import io.dropwizard.validation.PortRange;
140

141
public class ServerConfig {
142
    // Default port range (1-65535), allows 0 for dynamic allocation
143
    @PortRange
144
    private int serverPort;
145
    
146
    // Custom port range for admin interface
147
    @PortRange(min = 8080, max = 9999)
148
    private int adminPort;
149
    
150
    // High-numbered ports only
151
    @PortRange(min = 49152, max = 65535)
152
    private int ephemeralPort;
153
    
154
    // Well-known ports range
155
    @PortRange(min = 1, max = 1023)
156
    private int systemPort;
157
}
158
```
159

160
## Advanced Usage
161

162
### Complex Configuration Validation
163

164
```java
165
import io.dropwizard.validation.OneOf;
166
import io.dropwizard.validation.PortRange;
167

168
public class DatabaseConfig {
169
    @OneOf({"mysql", "postgresql", "oracle", "sqlserver"})
170
    private String databaseType;
171
    
172
    @PortRange(min = 1024, max = 65535)
173
    private int databasePort;
174
    
175
    @OneOf(value = {"READ_UNCOMMITTED", "READ_COMMITTED", "REPEATABLE_READ", "SERIALIZABLE"})
176
    private String isolationLevel;
177
    
178
    @OneOf(value = {"true", "false"}, message = "SSL must be 'true' or 'false'")
179
    private String sslEnabled;
180
}
181
```
182

183
### Case-Insensitive Environment Variables
184

185
```java
186
import io.dropwizard.validation.OneOf;
187

188
public class EnvironmentConfig {
189
    // Accept various capitalizations of boolean values
190
    @OneOf(
191
        value = {"true", "false", "yes", "no", "on", "off", "1", "0"}, 
192
        ignoreCase = true,
193
        message = "Must be a valid boolean: true/false, yes/no, on/off, or 1/0"
194
    )
195
    private String featureEnabled;
196
    
197
    // Accept common environment names with flexible formatting
198
    @OneOf(
199
        value = {"dev", "development", "test", "testing", "stage", "staging", "prod", "production"}, 
200
        ignoreCase = true,
201
        ignoreWhitespace = true
202
    )
203
    private String deploymentEnvironment;
204
}
205
```
206

207
### Validation Groups
208

209
```java
210
import io.dropwizard.validation.OneOf;
211
import io.dropwizard.validation.PortRange;
212

213
public interface Development {}
214
public interface Production {}
215

216
public class GroupedConfig {
217
    // Different allowed values for different environments
218
    @OneOf(value = {"h2", "hsqldb"}, groups = Development.class)
219
    @OneOf(value = {"mysql", "postgresql"}, groups = Production.class)
220
    private String databaseType;
221
    
222
    // Different port ranges for different environments
223
    @PortRange(min = 8080, max = 8090, groups = Development.class)
224
    @PortRange(min = 80, max = 443, groups = Production.class)
225
    private int httpPort;
226
}
227
```
228

229
### Integration with Bean Validation
230

231
```java
232
import io.dropwizard.validation.OneOf;
233
import io.dropwizard.validation.PortRange;
234
import javax.validation.constraints.NotNull;
235
import javax.validation.constraints.NotBlank;
236

237
public class ValidatedConfig {
238
    @NotNull
239
    @NotBlank
240
    @OneOf({"http", "https"})
241
    private String protocol;
242
    
243
    @NotNull
244
    @PortRange(min = 1, max = 65535)
245
    private Integer port;
246
    
247
    // Combining with other validation annotations
248
    @NotBlank
249
    @OneOf(value = {"json", "xml", "yaml"}, ignoreCase = true)
250
    private String responseFormat;
251
}
252
```
253

254
## Validation Behavior
255

256
### OneOf Validator
257

258
- **Case Sensitivity**: By default, matching is case-sensitive. Set `ignoreCase = true` for case-insensitive matching.
259
- **Whitespace Handling**: By default, whitespace is significant. Set `ignoreWhitespace = true` to trim leading/trailing whitespace before comparison.
260
- **Null Values**: `null` values are considered valid. Use `@NotNull` to reject null values.
261
- **Empty Strings**: Empty strings are treated as regular values and must be explicitly included in the allowed values array if permitted.
262

263
### PortRange Validator
264

265
- **Port 0 Special Case**: Port 0 is always considered valid regardless of the min/max range, as it represents dynamic port allocation.
266
- **Range Validation**: Validates that the port number falls within the specified min/max range (inclusive).
267
- **Null Values**: `null` values are considered valid. Use `@NotNull` to reject null values.
268
- **Default Range**: Without parameters, validates ports 1-65535 plus port 0.
269

270
## Integration Notes
271

272
- Both validators integrate seamlessly with Dropwizard's Jersey resource validation
273
- Validators work with standard Bean Validation groups for conditional validation
274
- Custom error messages support standard Bean Validation message interpolation
275
- These validators are commonly used in Dropwizard configuration classes