com.tangosol.util

Interface ValueExtractor<T,E>

Type Parameters:

T - the type of the value to extract from

E - the type of value that will be extracted

All Superinterfaces:

CanonicallyNamed, Function<T,E>, Remote.Function<T,E>, Remote.ToDoubleFunction<T>, Remote.ToIntFunction<T>, Remote.ToLongFunction<T>, Serializable, ToDoubleFunction<T>, ToIntFunction<T>, ToLongFunction<T>

All Known Subinterfaces:

IndexAwareExtractor<T,E>

All Known Implementing Classes:

AbstractCompositeExtractor, AbstractExtractor, ChainedExtractor, ComparisonValueExtractor, ConditionalExtractor, DeserializationAccelerator, EntryExtractor, IdentityExtractor, KeyExtractor, MultiExtractor, MvelExtractor, NullImplementation.NullValueExtractor, PartitionedJCacheStatistics.CacheStatisticsExtractor, PofExtractor, PropertySet, ReflectionExtractor, UniversalExtractor

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface ValueExtractor<T,E>
extends Remote.Function<T,E>, Remote.ToIntFunction<T>, Remote.ToLongFunction<T>, Remote.ToDoubleFunction<T>, CanonicallyNamed

ValueExtractor is used to both extract values (for example, for sorting or filtering) from an object, and to provide an identity for that extraction.

Important Note: all classes that implement ValueExtractor interface must explicitly implement the hashCode() and equals() methods in a way that is based solely on the object's serializable state. Additionally, CanonicallyNamed provides a means for ValueExtractor implementations to suggest two implementations extract the same logical value with different implementations. Both hashCode(), equals() and CanonicallyNamed.getCanonicalName() should consistently be symmetric between implementations.

Author:

cp/gg 2002.10.31, as 2014.06.22

Method Summary

Modifier and Type	Method and Description
default <V> ValueExtractor<T,V>	andThen(ValueExtractor<? super E,? extends V> after) Returns a composed extractor that first applies this extractor to its input, and then applies the after extractor to the result.
default E	apply(T value)
default double	applyAsDouble(T value)
default int	applyAsInt(T value)
default long	applyAsLong(T value)
default <V> ValueExtractor<V,E>	compose(ValueExtractor<? super V,? extends T> before) Returns a composed extractor that first applies the before extractor to its input, and then applies this extractor to the result.
boolean	equals(Object o) This instance is considered equal to parameter o when both have same non-null getCanonicalName().
E	extract(T target) Extract the value from the passed object.
default ValueExtractor<T,E>	fromKey() Obtain a version of this ValueExtractor that targets an entry's key.
default String	getCanonicalName() Return the canonical name for this extractor.
default int	getTarget() Return AbstractExtractor.VALUE.
int	hashCode() Return the hashCode for this extractor.
static <T> ValueExtractor<T,T>	identity() Returns an extractor that always returns its input argument.
static <T,E> ValueExtractor<T,E>	identityCast() Returns an extractor that casts its input argument.
static <T,E> ValueExtractor<T,E>	of(ValueExtractor<T,E> extractor) Helper method to allow composition/chaining of extractors.

Methods inherited from interface com.tangosol.util.function.Remote.Function

andThen, compose

Methods inherited from interface java.util.function.Function

andThen, compose

Method Detail

extract

E extract(T target)

Extract the value from the passed object. The returned value may be null. For intrinsic types, the returned value is expected to be a standard wrapper type in the same manner that reflection works; for example, int would be returned as a java.lang.Integer.

Parameters:

target - the object to extract the value from

Returns:

the extracted value; null is an acceptable value

Throws:

ClassCastException - if this ValueExtractor is incompatible with the passed object to extract a value from and the implementation requires the passed object to be of a certain type

WrapperException - if this ValueExtractor encounters an exception in the course of extracting the value

IllegalArgumentException - if this ValueExtractor cannot handle the passed object for any other reason; an implementor should include a descriptive message

getTarget

default int getTarget()

Return AbstractExtractor.VALUE.

Returns:

AbstractExtractor.VALUE

Since:

12.2.1.4

getCanonicalName

default String getCanonicalName()

Return the canonical name for this extractor.

A canonical name uniquely identifies what is to be extracted, but not how it is to be extracted. Thus two different extractor implementations with the same non-null canonical name are considered to be equal, and should reflect this in their implementations of hashCode and equals.

Canonical names for properties are designated by their property name in camel case, for instance a Java Bean with method getFooBar would have a property named fooBar, and would have fooBar as its canonical name.

Canonical names for zero-arg method invocations are the method name followed by ().

Dots in a canonical name delimit one or more property/method accesses represented by a chaining ValueExtractor such as ChainedExtractor or PofExtractor(Class, PofNavigator, String).

There is currently no canonical name format for methods which take parameters and as such they must return a canonical name of null.

Specified by:

getCanonicalName in interface CanonicallyNamed

Returns:

the extractor's canonical name, or null

apply

default E apply(T value)

Specified by:

apply in interface Function<T,E>

applyAsInt

default int applyAsInt(T value)

Specified by:

applyAsInt in interface ToIntFunction<T>

applyAsLong

default long applyAsLong(T value)

Specified by:

applyAsLong in interface ToLongFunction<T>

applyAsDouble

default double applyAsDouble(T value)

Specified by:

applyAsDouble in interface ToDoubleFunction<T>

equals

boolean equals(Object o)

This instance is considered equal to parameter o when both have same non-null getCanonicalName().

Note: Fall back to implementation specific equals/hashCode when both canonical names are null.

Overrides:

equals in class Object

Returns:

true iff the extractors are deemed to be equal

hashCode

int hashCode()

Return the hashCode for this extractor.

Note two extractors with the same non-null canonical name are expected to also have the same hashCode.

Note: Fall back to implementation specific equals/hashCode when canonical name is null.

Overrides:

hashCode in class Object

Returns:

hashCode computed from non-null canonical name.

identity

static <T> ValueExtractor<T,T> identity()

Returns an extractor that always returns its input argument.

Specified by:

identity in interface Function<T,E>

Specified by:

identity in interface Remote.Function<T,E>

Type Parameters:

T - the type of the input and output objects to the function

Returns:

an extractor that always returns its input argument

identityCast

static <T,E> ValueExtractor<T,E> identityCast()

Returns an extractor that casts its input argument.

Type Parameters:

T - the type of the input objects to the function

E - the type of the output objects to the function

Returns:

an extractor that always returns its input argument

of

static <T,E> ValueExtractor<T,E> of(ValueExtractor<T,E> extractor)

Helper method to allow composition/chaining of extractors.

This method is helpful whenever a lambda-based extractors need to be composed using compose or andThen method, as it eliminates the need for casting or intermediate variables.

For example, instead of writing

     ((ValueExtractor<Person, Address>) Person::getAddress).andThen(Address::getState)
 

or

     ValueExtractor<Person, Address> addressExtractor = Person::getAddress;
     addressExtractor.andThen(Address::getState)
 

it allows you to achieve the same goal by simply calling

     ValueExtractor.of(Person::getAddress).andThen(Address::getState)
 

Type Parameters:

T - the type of the value to extract from

E - the type of value that will be extracted

Parameters:

extractor - the extractor to return

Returns:

the specified extractor

compose

default <V> ValueExtractor<V,E> compose(ValueExtractor<? super V,? extends T> before)

Returns a composed extractor that first applies the before extractor to its input, and then applies this extractor to the result. If evaluation of either extractor throws an exception, it is relayed to the caller of the composed extractor.

Type Parameters:

V - the type of input to the before extractor, and to the composed extractor

Parameters:

before - the extractor to apply before this extractor is applied

Returns:

a composed extractor that first applies the before extractor and then applies this extractor

Throws:

NullPointerException - if the passed extractor is null

See Also:

andThen(ValueExtractor)

andThen

default <V> ValueExtractor<T,V> andThen(ValueExtractor<? super E,? extends V> after)

Returns a composed extractor that first applies this extractor to its input, and then applies the after extractor to the result. If evaluation of either extractor throws an exception, it is relayed to the caller of the composed extractor.

Type Parameters:

V - the type of output of the after extractor, and of the composed extractor

Parameters:

after - the extractor to apply after this extractor is applied

Returns:

a composed extractor that first applies this extractor and then applies the after extractor

Throws:

NullPointerException - if the passed extractor is null

See Also:

compose(ValueExtractor)

fromKey

default ValueExtractor<T,E> fromKey()

Obtain a version of this ValueExtractor that targets an entry's key.

Returns:

a version of this ValueExtractor that targets an entry's key