This class is responsible for converting arbitrary data, sent to us by the web browser, into * validated data structures that the server-side code can use. For example:
*
* private enum Gender { MALE, FEMALE }
*
* private static final FormField NAME_FIELD = FormField.named("name")
* .matches("[a-z]+")
* .range(atMost(16))
* .required()
* .build();
*
* private static final FormField GENDER_FIELD = FormField.named("gender")
* .asEnum(Gender.class)
* .required()
* .build();
*
* public Person makePerson(Map params) {
* Person.Builder person = new Person.Builder();
* for (String name : NAME_FIELD.extract(params).asSet()) {
* person.setName(name);
* }
* for (Gender name : GENDER_FIELD.extract(params).asSet()) {
* person.setGender(name);
* }
* return person.build();
* }
*
* This class provides full type-safety if and only if you statically initialize * your FormField objects and write a unit test that causes the class to be loaded. * *
When values passed to {@link #convert} or {@link #extract} don't meet the contract, * {@link FormFieldException} will be thrown, which provides the field name and a short error * message that's safe to pass along to the client. * *
You can safely throw {@code FormFieldException} from within your validator functions, and * the field name will automatically be propagated into the exception object for you. * *
In situations when you're validating lists or maps, you'll end up with a hierarchical field * naming structure. For example, if you were validating a list of maps, an error generated by the * {@code bar} field of the fifth item in the {@code foo} field would have a fully-qualified field * name of: {@code foo[5][bar]}. * *
You should never assign a partially constructed {@code FormField.Builder} to a variable or * constant. Instead, you should use {@link #asBuilder()} or {@link #asBuilderNamed(String)}. * *
Here is an example of how you might go about defining library definitions:
*
* final class FormFields {
* private static final FormField COUNTRY_CODE =
* FormField.named("countryCode")
* .range(Range.singleton(2))
* .uppercased()
* .in(ImmutableSet.copyOf(Locale.getISOCountries()))
* .build();
* }
*
* final class Form {
* private static final FormField COUNTRY_CODE_FIELD =
* FormFields.COUNTRY_CODE.asBuilder()
* .required()
* .build();
* }
*
* @param input value type
* @param Here's an example of how you'd use this feature: * *
* private static final FormField<String, String> REGISTRAR_NAME_FIELD =
* FormField.named("name")
* .emptyToNull()
* .required()
* .build();
*
* private static final FormField<Map<String, ?>, Registrar> REGISTRAR_FIELD =
* FormField.mapNamed("registrar")
* .transform(Registrar.class, new Function<Map<String, ?>, Registrar>() {
* @Nullable
* @Override
* public Registrar apply(@Nullable Map<String, ?> params) {
* Registrar.Builder builder = new Registrar.Builder();
* for (String name : REGISTRAR_NAME_FIELD.extractUntyped(params).asSet()) {
* builder.setName(name);
* }
* return builder.build();
* }})
* .build();
*
* When a {@link FormFieldException} is thrown, it'll be propagated to create a fully-qualified * field name. For example, if the JSON input is
{registrar: {name: ""}} then the
* {@link FormFieldException#getFieldName() field name} will be {@code registrar.name}.
*/
public static BuilderThis is the same as saying: {@code field.convert(valueMap.get(field.name())}
*
* @throws FormFieldException if value does not meet expected contracts.
*/
@Detainted
public Optional {@code null} values are passed through.
*
* @throws IllegalStateException if current output type is not a String.
*/
public Builder {@code null} values are passed through.
*
* @throws IllegalStateException if current output type is not a String.
*/
public Builder {@code null} values are passed through.
*
* @throws IllegalStateException if current output type is not a String.
*/
public Builder {@code null} values are passed through.
*
* @param pattern is used to validate the user input. It matches against the whole string, so
* you don't need to use the ^$ characters.
* @param errorMessage is a helpful error message, which should include an example. If this is
* not provided, a default error message will be shown that includes the regexp pattern.
* @throws IllegalStateException if current output type is not a {@link CharSequence}.
* @see #matches(Pattern)
*/
public Builder {@code null} values are passed through.
*
* @param matcher indicates which characters are to be retained
* @throws IllegalStateException if current output type is not a {@link CharSequence}
*/
public Builder The following input value types are supported:
*
* {@code null} values are passed through. Please note that setting a lower bound on your
* range does not imply {@link #required()}, as range checking only applies to non-{@code null}
* values.
*
* @throws IllegalStateException if current output type is not one of the above types.
*/
public Builder {@code null} values are passed through.
*
* @throws IllegalArgumentException if {@code values} is empty.
*/
public Builder Your {@code transform} function is expected to pass-through {@code null} values as a
* no-op, since it's up to {@link #required()} to block them. You might also want to consider
* using a try block that rethrows exceptions as {@link FormFieldException}.
*
* Here's an example of how you'd convert from String to Integer:
*
* Please see {@link #transform(Class, Function)} for information about the contract to
* which {@code transform} is expected to conform.
*/
public Builder {@code null} values are passed through.
*
* @throws IllegalArgumentException if {@code enumClass} is not an enum class.
* @throws IllegalStateException if current output type is not a String.
*/
public The current object definition will be applied to each item in the list. If a
* {@link FormFieldException} is thrown when processing an item, then its
* {@link FormFieldException#getFieldName() fieldName} will be rewritten to include the index,
* e.g. {@code name} becomes {@code name[0]}.
*
* The outputted list will be an {@link ImmutableList}. This is not reflected in the generic
* typing for the sake of brevity.
*
* A {@code null} value for list will be passed through. List items that convert to
* {@code null} will be discarded (since {@code ImmutableList} does not permit {@code null}
* values).
*/
public Builder The behavior of this method is counter-intuitive. It behaves similar to {@link #asList()}
* in the sense that all transforms specified before this method will be applied to the
* individual resulting list items.
*
* For example, to turn a comma-delimited string into an enum list: You'll notice that the transforms specified before this method are applied to each list
* item. However unlike {@link #asList()}, if an error is thrown on an individual item, then
* {@link FormFieldException#getFieldName()} will not contain the index.
*
* @throws IllegalStateException If either the current input type isn't String.
*/
public Builder
*
*
*
* FormField.named("foo", String.class)
* .transform(Integer.class, new Function<String, Integer>() {
* @Nullable
* @Override
* public Integer apply(@Nullable String input) {
* try {
* return input != null ? Integer.parseInt(input) : null;
* } catch (IllegalArgumentException e) {
* throw new FormFieldException("Invalid number.", e);
* }
* }})
* .build();
*
* @see #transform(Function)
*/
public {@code
*
* private static final FormField
*
*