/*
 * Bean Validation API
 *
 * License: Apache License, Version 2.0
 * See the license.txt file in the root directory or <http://www.apache.org/licenses/LICENSE-2.0>.
 */
package javax.validation.valueextraction;

import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.OptionalInt;
import java.util.Set;

import javax.validation.Path;

Defines the logic used to extract the values from a container object of type T.

A value extractor for a generic type such as Optional, List or Map is tied to one specific type parameter of T. The ExtractedValue annotation is used to mark that type parameter. A value extractor for a non-generic type such as OptionalInt needs to declare the type of the wrapped element(s) using ExtractedValue.type().

The extracted values are passed to the corresponding method of the ValueReceiver.

A typical value extractor implementation for List may look like this:

public class ListValueExtractor implements
        ValueExtractor<List<@ExtractedValue ?>> {
    @Override
    public void extractValues(List<?> originalValue, ValueReceiver receiver) {
        for ( int i = 0; i < originalValue.size(); i++ ) {
            receiver.indexedValue( "<list element>", i, originalValue.get( i ) );
        }
    }
}
Author:Gunnar Morling, Guillaume Smet
Type parameters:
  • <T> – the container type handled by a specific implementation
See Also:
Since:2.0
/** * Defines the logic used to extract the values from a container object of type {@code T}. * <p> * A value extractor for a generic type such as {@link Optional}, {@link List} or {@link Map} * is tied to one specific type parameter of {@code T}. The {@link ExtractedValue} annotation * is used to mark that type parameter. A value extractor for a non-generic type such as * {@link OptionalInt} needs to declare the type of the wrapped element(s) using * {@link ExtractedValue#type()}. * <p> * The extracted values are passed to the corresponding method of the {@link ValueReceiver}. * <p> * A typical value extractor implementation for {@code List} may look like this: * * <pre> * public class ListValueExtractor implements * ValueExtractor&lt;List&lt;&#064;ExtractedValue ?&gt;&gt; { * * &#064;Override * public void extractValues(List&lt;?&gt; originalValue, ValueReceiver receiver) { * for ( int i = 0; i &lt; originalValue.size(); i++ ) { * receiver.indexedValue( "&lt;list element&gt;", i, originalValue.get( i ) ); * } * } * } * </pre> * * @param <T> the container type handled by a specific implementation * * @author Gunnar Morling * @author Guillaume Smet * @see ExtractedValue * @see UnwrapByDefault * @since 2.0 */
public interface ValueExtractor<T> {
Extracts the values to validate from the original object.
Params:
  • originalValue – the original value from which to extract the values, never null
  • receiver – the corresponding ValueReceiver
/** * Extracts the values to validate from the original object. * * @param originalValue the original value from which to extract the values, never * {@code null} * @param receiver the corresponding {@code ValueReceiver} */
void extractValues(T originalValue, ValueReceiver receiver);
Provides a set of methods receiving value extracted by the ValueExtractor.

The value has to be passed to the method corresponding best to the type of the original value.

Since:2.0
/** * Provides a set of methods receiving value extracted by the {@link ValueExtractor}. * <p> * The value has to be passed to the method corresponding best to the type of the * original value. * * @since 2.0 */
interface ValueReceiver {
Receives the value extracted from an object.
Params:
  • nodeName – the name of the node representing the container element. If not null, the name will be used when adding a container element node to the Path
  • object – the value to validate
/** * Receives the value extracted from an object. * * @param nodeName the name of the node representing the container element. If not * {@code null}, the name will be used when adding a container element node to the * {@link Path} * @param object the value to validate */
void value(String nodeName, Object object);
Receives the value extracted from an iterable object that is not indexed (e.g. a Iterable, Set or a Map).
Params:
  • nodeName – the name of the node representing the container element. If not null, the name will be used when adding a container element node to the Path
  • object – the value to validate
/** * Receives the value extracted from an iterable object that is not indexed (e.g. * a {@link Iterable}, {@link Set} or a {@link Map}). * * @param nodeName the name of the node representing the container element. If not * {@code null}, the name will be used when adding a container element node to the * {@link Path} * @param object the value to validate */
void iterableValue(String nodeName, Object object);
Receives the value extracted from an indexed object (e.g. a List).
Params:
  • nodeName – the name of the node representing the container element. If not null, the name will be used when adding a container element node to the Path
  • i – the index of the value in the original object
  • object – the value to validate
/** * Receives the value extracted from an indexed object (e.g. a {@link List}). * * @param nodeName the name of the node representing the container element. If not * {@code null}, the name will be used when adding a container element node to the * {@link Path} * @param i the index of the value in the original object * @param object the value to validate */
void indexedValue(String nodeName, int i, Object object);
Receives the value extracted from a keyed object (e.g. a Map).
Params:
  • nodeName – the name of the node representing the container element. If not null, the name will be used when adding a container element node to the Path
  • key – the key of the value in the original object
  • object – the value to validate
/** * Receives the value extracted from a keyed object (e.g. a {@link Map}). * * @param nodeName the name of the node representing the container element. If not * {@code null}, the name will be used when adding a container element node to the * {@link Path} * @param key the key of the value in the original object * @param object the value to validate */
void keyedValue(String nodeName, Object key, Object object); } }