play.data

Class Form<T>

java.lang.Object

play.data.Form<T>

Direct Known Subclasses:

DynamicForm

public class Form<T>
extends java.lang.Object

Helper to manage HTML form description, submission and validation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Form.Display Defines a form element's display name.
static class	Form.Field A form field.

Constructor Summary

Constructors

Constructor and Description
Form(java.lang.Class<T> clazz, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator) Creates a new Form.
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.lang.Class<?>[] groups, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator)
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.lang.Class<?> group, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator)
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.util.Map<java.lang.String,java.lang.String> data, java.util.List<ValidationError> errors, java.util.Optional<T> value, java.lang.Class<?>[] groups, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator) Creates a new Form.
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.util.Map<java.lang.String,java.lang.String> data, java.util.List<ValidationError> errors, java.util.Optional<T> value, java.lang.Class<?> group, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator)
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.util.Map<java.lang.String,java.lang.String> data, java.util.List<ValidationError> errors, java.util.Optional<T> value, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator)
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.util.Map<java.lang.String,java.lang.String> data, java.util.Map<java.lang.String,java.util.List<ValidationError>> errors, java.util.Optional<T> value, java.lang.Class<?>[] groups, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator) Deprecated. Deprecated as of 2.6.0. Replace the parameter Map<String,List<ValidationError>> with a simple List<ValidationError>.
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.util.Map<java.lang.String,java.lang.String> data, java.util.Map<java.lang.String,java.util.List<ValidationError>> errors, java.util.Optional<T> value, java.lang.Class<?> group, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator) Deprecated. Deprecated as of 2.6.0. Replace the parameter Map<String,List<ValidationError>> with a simple List<ValidationError>.
Form(java.lang.String rootName, java.lang.Class<T> clazz, java.util.Map<java.lang.String,java.lang.String> data, java.util.Map<java.lang.String,java.util.List<ValidationError>> errors, java.util.Optional<T> value, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator) Deprecated. Deprecated as of 2.6.0. Replace the parameter Map<String,List<ValidationError>> with a simple List<ValidationError>.
Form(java.lang.String rootName, java.lang.Class<T> clazz, MessagesApi messagesApi, Formatters formatters, javax.validation.Validator validator)

Method Summary

Modifier and Type	Method and Description
java.util.List<ValidationError>	allErrors() Returns all errors.
Form.Field	apply(java.lang.String key) Retrieves a field.
Form<T>	bind(com.fasterxml.jackson.databind.JsonNode data, java.lang.String... allowedFields) Binds Json data to this form - that is, handles form submission.
Form<T>	bind(java.util.Map<java.lang.String,java.lang.String> data, java.lang.String... allowedFields) Binds data to this form - that is, handles form submission.
Form<T>	bindFromRequest(Http.Request request, java.lang.String... allowedFields) Binds request data to this form - that is, handles form submission.
Form<T>	bindFromRequest(java.util.Map<java.lang.String,java.lang.String[]> requestData, java.lang.String... allowedFields) Binds request data to this form - that is, handles form submission.
Form<T>	bindFromRequest(java.lang.String... allowedFields) Binds request data to this form - that is, handles form submission.
protected T	blankInstance()
java.util.Map<java.lang.String,java.lang.String>	data() Deprecated. Deprecated as of 2.6.0. Use rawData() instead which returns an unmodifiable map.
void	discardErrors() Deprecated. Deprecated as of 2.6.0. Use discardingErrors() instead.
Form<T>	discardingErrors()
ValidationError	error(java.lang.String key) Deprecated. Deprecated as of 2.6.0. Use getError(String) instead.
java.util.Map<java.lang.String,java.util.List<ValidationError>>	errors() Deprecated. Deprecated as of 2.6.0. Use allErrors() instead.
java.util.List<ValidationError>	errors(java.lang.String key)
com.fasterxml.jackson.databind.JsonNode	errorsAsJson()
com.fasterxml.jackson.databind.JsonNode	errorsAsJson(Lang lang) Returns the form errors serialized as Json using the given Lang.
Form.Field	field(java.lang.String key) Retrieves a field.
Form<T>	fill(T value) Populates this form with an existing value, used for edit forms.
T	get() Gets the concrete value only if the submission was a success.
protected java.lang.Object[]	getArgumentsForConstraint(java.lang.String objectName, java.lang.String field, javax.validation.metadata.ConstraintDescriptor<?> descriptor)
java.lang.Class<T>	getBackedType()
java.util.Optional<ValidationError>	getError(java.lang.String key)
java.util.Optional<ValidationError>	getGlobalError() Retrieves the first global error (an error without any key), if it exists.
protected java.lang.String	getMessageForConstraintViolation(javax.validation.ConstraintViolation<java.lang.Object> violation) When dealing with @ValidateWith annotations, and message parameter is not used in the annotation, extract the message from validator's getErrorMessageKey() method
ValidationError	globalError() Deprecated. Deprecated as of 2.6.0. Use getGlobalError() instead.
java.util.List<ValidationError>	globalErrors() Retrieve all global errors - errors without a key.
boolean	hasErrors()
boolean	hasGlobalErrors()
java.lang.String	name()
java.util.Map<java.lang.String,java.lang.String>	rawData()
void	reject(java.lang.String error) Deprecated. Deprecated as of 2.6.0. Use withGlobalError(String) instead.
void	reject(java.lang.String error, java.util.List<java.lang.Object> args) Deprecated. Deprecated as of 2.6.0. Use withGlobalError(String, List) instead.
void	reject(java.lang.String key, java.lang.String error) Deprecated. Deprecated as of 2.6.0. Use withError(String, String) instead.
void	reject(java.lang.String key, java.lang.String error, java.util.List<java.lang.Object> args) Deprecated. Deprecated as of 2.6.0. Use withError(String, String, List) instead.
void	reject(ValidationError error) Deprecated. Deprecated as of 2.6.0. Use withError(ValidationError) instead.
protected java.util.Map<java.lang.String,java.lang.String>	requestData(Http.Request request)
java.lang.String	toString()
java.util.Optional<T>	value()
Form<T>	withError(java.lang.String key, java.lang.String error)
Form<T>	withError(java.lang.String key, java.lang.String error, java.util.List<java.lang.Object> args)
Form<T>	withError(ValidationError error)
Form<T>	withGlobalError(java.lang.String error)
Form<T>	withGlobalError(java.lang.String error, java.util.List<java.lang.Object> args)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Form

public Form(java.lang.Class<T> clazz,
            MessagesApi messagesApi,
            Formatters formatters,
            javax.validation.Validator validator)

Creates a new Form. Consider using a FormFactory rather than this constructor.

Parameters:

clazz - wrapped class

messagesApi - messagesApi component.

formatters - formatters component.

validator - validator component.

Form

public Form(java.lang.String rootName,
            java.lang.Class<T> clazz,
            MessagesApi messagesApi,
            Formatters formatters,
            javax.validation.Validator validator)

Form

public Form(java.lang.String rootName,
            java.lang.Class<T> clazz,
            java.lang.Class<?> group,
            MessagesApi messagesApi,
            Formatters formatters,
            javax.validation.Validator validator)

Form

public Form(java.lang.String rootName,
            java.lang.Class<T> clazz,
            java.lang.Class<?>[] groups,
            MessagesApi messagesApi,
            Formatters formatters,
            javax.validation.Validator validator)

Form

public Form(java.lang.String rootName,
            java.lang.Class<T> clazz,
            java.util.Map<java.lang.String,java.lang.String> data,
            java.util.List<ValidationError> errors,
            java.util.Optional<T> value,
            MessagesApi messagesApi,
            Formatters formatters,
            javax.validation.Validator validator)

Form

@Deprecated
public Form(java.lang.String rootName,
                        java.lang.Class<T> clazz,
                        java.util.Map<java.lang.String,java.lang.String> data,
                        java.util.Map<java.lang.String,java.util.List<ValidationError>> errors,
                        java.util.Optional<T> value,
                        MessagesApi messagesApi,
                        Formatters formatters,
                        javax.validation.Validator validator)

Deprecated. Deprecated as of 2.6.0. Replace the parameter Map<String,List<ValidationError>> with a simple List<ValidationError>.

Parameters:

rootName - the root name.

clazz - wrapped class

data - the current form data (used to display the form)

errors - the collection of errors associated with this form

value - optional concrete value of type T if the form submission was successful

messagesApi - needed to look up various messages

formatters - used for parsing and printing form fields

validator - the validator component.

Form

public Form(java.lang.String rootName,
            java.lang.Class<T> clazz,
            java.util.Map<java.lang.String,java.lang.String> data,
            java.util.List<ValidationError> errors,
            java.util.Optional<T> value,
            java.lang.Class<?> group,
            MessagesApi messagesApi,
            Formatters formatters,
            javax.validation.Validator validator)

Form

@Deprecated
public Form(java.lang.String rootName,
                        java.lang.Class<T> clazz,
                        java.util.Map<java.lang.String,java.lang.String> data,
                        java.util.Map<java.lang.String,java.util.List<ValidationError>> errors,
                        java.util.Optional<T> value,
                        java.lang.Class<?> group,
                        MessagesApi messagesApi,
                        Formatters formatters,
                        javax.validation.Validator validator)

Deprecated. Deprecated as of 2.6.0. Replace the parameter Map<String,List<ValidationError>> with a simple List<ValidationError>.

Parameters:

rootName - the root name.

clazz - wrapped class

data - the current form data (used to display the form)

errors - the collection of errors associated with this form

value - optional concrete value of type T if the form submission was successful

group - the class with the group.

messagesApi - needed to look up various messages

formatters - used for parsing and printing form fields

validator - the validator component.

Form

public Form(java.lang.String rootName,
            java.lang.Class<T> clazz,
            java.util.Map<java.lang.String,java.lang.String> data,
            java.util.List<ValidationError> errors,
            java.util.Optional<T> value,
            java.lang.Class<?>[] groups,
            MessagesApi messagesApi,
            Formatters formatters,
            javax.validation.Validator validator)

Creates a new Form. Consider using a FormFactory rather than this constructor.

Parameters:

rootName - the root name.

clazz - wrapped class

data - the current form data (used to display the form)

errors - the collection of errors associated with this form

value - optional concrete value of type T if the form submission was successful

groups - the array of classes with the groups.

messagesApi - needed to look up various messages

formatters - used for parsing and printing form fields

validator - the validator component.

Form

@Deprecated
public Form(java.lang.String rootName,
                        java.lang.Class<T> clazz,
                        java.util.Map<java.lang.String,java.lang.String> data,
                        java.util.Map<java.lang.String,java.util.List<ValidationError>> errors,
                        java.util.Optional<T> value,
                        java.lang.Class<?>[] groups,
                        MessagesApi messagesApi,
                        Formatters formatters,
                        javax.validation.Validator validator)

Deprecated. Deprecated as of 2.6.0. Replace the parameter Map<String,List<ValidationError>> with a simple List<ValidationError>.

Parameters:

rootName - the root name.

clazz - wrapped class

data - the current form data (used to display the form)

errors - the collection of errors associated with this form

value - optional concrete value of type T if the form submission was successful

groups - the array of classes with the groups.

messagesApi - needed to look up various messages

formatters - used for parsing and printing form fields

validator - the validator component.

Method Detail

getBackedType

public java.lang.Class<T> getBackedType()

blankInstance

protected T blankInstance()

requestData

protected java.util.Map<java.lang.String,java.lang.String> requestData(Http.Request request)

bindFromRequest

public Form<T> bindFromRequest(java.lang.String... allowedFields)

Binds request data to this form - that is, handles form submission.

Parameters:

allowedFields - the fields that should be bound to the form, all fields if not specified.

Returns:

a copy of this form filled with the new data

bindFromRequest

public Form<T> bindFromRequest(Http.Request request,
                               java.lang.String... allowedFields)

Binds request data to this form - that is, handles form submission.

Parameters:

request - the request to bind data from.

allowedFields - the fields that should be bound to the form, all fields if not specified.

Returns:

a copy of this form filled with the new data

bindFromRequest

public Form<T> bindFromRequest(java.util.Map<java.lang.String,java.lang.String[]> requestData,
                               java.lang.String... allowedFields)

Binds request data to this form - that is, handles form submission.

Parameters:

requestData - the map of data to bind from

allowedFields - the fields that should be bound to the form, all fields if not specified.

Returns:

a copy of this form filled with the new data

bind

public Form<T> bind(com.fasterxml.jackson.databind.JsonNode data,
                    java.lang.String... allowedFields)

Binds Json data to this form - that is, handles form submission.

Parameters:

data - data to submit

allowedFields - the fields that should be bound to the form, all fields if not specified.

Returns:

a copy of this form filled with the new data

getArgumentsForConstraint

protected java.lang.Object[] getArgumentsForConstraint(java.lang.String objectName,
                                                       java.lang.String field,
                                                       javax.validation.metadata.ConstraintDescriptor<?> descriptor)

getMessageForConstraintViolation

protected java.lang.String getMessageForConstraintViolation(javax.validation.ConstraintViolation<java.lang.Object> violation)

When dealing with @ValidateWith annotations, and message parameter is not used in the annotation, extract the message from validator's getErrorMessageKey() method

Parameters:

violation - the constraint violation.

Returns:

the message associated with the constraint violation.

bind

public Form<T> bind(java.util.Map<java.lang.String,java.lang.String> data,
                    java.lang.String... allowedFields)

Binds data to this form - that is, handles form submission.

Parameters:

data - data to submit

allowedFields - the fields that should be bound to the form, all fields if not specified.

Returns:

a copy of this form filled with the new data

data

@Deprecated
public java.util.Map<java.lang.String,java.lang.String> data()

Deprecated. Deprecated as of 2.6.0. Use rawData() instead which returns an unmodifiable map.

Returns:

the actual form data.

rawData

public java.util.Map<java.lang.String,java.lang.String> rawData()

Returns:

the actual form data as unmodifiable map.

name

public java.lang.String name()

value

public java.util.Optional<T> value()

Returns:

the actual form value - even when the form contains validation errors.

fill

public Form<T> fill(T value)

Populates this form with an existing value, used for edit forms.

Parameters:

value - existing value of type T used to fill this form

Returns:

a copy of this form filled with the new data

hasErrors

public boolean hasErrors()

Returns:

true if there are any errors related to this form.

hasGlobalErrors

public boolean hasGlobalErrors()

Returns:

true if there any global errors related to this form.

globalErrors

public java.util.List<ValidationError> globalErrors()

Retrieve all global errors - errors without a key.

Returns:

All global errors.

globalError

@Deprecated
public ValidationError globalError()

Deprecated. Deprecated as of 2.6.0. Use getGlobalError() instead.

Retrieves the first global error (an error without any key), if it exists.

Returns:

An error or null.

getGlobalError

public java.util.Optional<ValidationError> getGlobalError()

Retrieves the first global error (an error without any key), if it exists.

Returns:

An error.

errors

@Deprecated
public java.util.Map<java.lang.String,java.util.List<ValidationError>> errors()

Deprecated. Deprecated as of 2.6.0. Use allErrors() instead.

Returns all errors.

Returns:

All errors associated with this form.

allErrors

public java.util.List<ValidationError> allErrors()

Returns all errors.

Returns:

All errors associated with this form.

errors

public java.util.List<ValidationError> errors(java.lang.String key)

Parameters:

key - the field name associated with the error.

Returns:

All errors for this key.

error

@Deprecated
public ValidationError error(java.lang.String key)

Deprecated. Deprecated as of 2.6.0. Use getError(String) instead.

Parameters:

key - the field name associated with the error.

Returns:

an error by key, or null.

getError

public java.util.Optional<ValidationError> getError(java.lang.String key)

Parameters:

key - the field name associated with the error.

Returns:

an error by key

errorsAsJson

public com.fasterxml.jackson.databind.JsonNode errorsAsJson()

Returns:

the form errors serialized as Json.

errorsAsJson

public com.fasterxml.jackson.databind.JsonNode errorsAsJson(Lang lang)

Returns the form errors serialized as Json using the given Lang.

Parameters:

lang - the language to use.

Returns:

the JSON node containing the errors.

get

public T get()

Gets the concrete value only if the submission was a success. If the form is invalid because of validation errors this method will throw an exception. If you want to retrieve the value even when the form is invalid use value() instead.

Returns:

the concrete value.

Throws:

java.lang.IllegalStateException - if there are errors binding the form, including the errors as JSON in the message

reject

@Deprecated
public void reject(ValidationError error)

Deprecated. Deprecated as of 2.6.0. Use withError(ValidationError) instead.

Adds an error to this form.

Parameters:

error - the ValidationError to add.

withError

public Form<T> withError(ValidationError error)

Parameters:

error - the ValidationError to add to the returned form.

Returns:

a copy of this form with the given error added.

reject

@Deprecated
public void reject(java.lang.String key,
                               java.lang.String error,
                               java.util.List<java.lang.Object> args)

Deprecated. Deprecated as of 2.6.0. Use withError(String, String, List) instead.

Adds an error to this form.

Parameters:

key - the error key

error - the error message

args - the error arguments

withError

public Form<T> withError(java.lang.String key,
                         java.lang.String error,
                         java.util.List<java.lang.Object> args)

Parameters:

key - the error key

error - the error message

args - the error arguments

Returns:

a copy of this form with the given error added.

reject

@Deprecated
public void reject(java.lang.String key,
                               java.lang.String error)

Deprecated. Deprecated as of 2.6.0. Use withError(String, String) instead.

Adds an error to this form.

Parameters:

key - the error key

error - the error message

withError

public Form<T> withError(java.lang.String key,
                         java.lang.String error)

Parameters:

key - the error key

error - the error message

Returns:

a copy of this form with the given error added.

reject

@Deprecated
public void reject(java.lang.String error,
                               java.util.List<java.lang.Object> args)

Deprecated. Deprecated as of 2.6.0. Use withGlobalError(String, List) instead.

Adds a global error to this form.

Parameters:

error - the error message

args - the error arguments

withGlobalError

public Form<T> withGlobalError(java.lang.String error,
                               java.util.List<java.lang.Object> args)

Parameters:

error - the global error message

args - the global error arguments

Returns:

a copy of this form with the given global error added.

reject

@Deprecated
public void reject(java.lang.String error)

Deprecated. Deprecated as of 2.6.0. Use withGlobalError(String) instead.

Adds a global error to this form.

Parameters:

error - the error message.

withGlobalError

public Form<T> withGlobalError(java.lang.String error)

Parameters:

error - the global error message

Returns:

a copy of this form with the given global error added.

discardErrors

@Deprecated
public void discardErrors()

Deprecated. Deprecated as of 2.6.0. Use discardingErrors() instead.

Discards errors of this form

discardingErrors

public Form<T> discardingErrors()

Returns:

a copy of this form but with the errors discarded.

apply

public Form.Field apply(java.lang.String key)

Retrieves a field.

Parameters:

key - field name

Returns:

the field (even if the field does not exist you get a field)

field

public Form.Field field(java.lang.String key)

Retrieves a field.

Parameters:

key - field name

Returns:

the field (even if the field does not exist you get a field)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object