Package 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, ChainedFragmentExtractor, ComparisonValueExtractor, ConditionalExtractor, DeserializationAccelerator, EntryExtractor, FragmentExtractor, IdentityExtractor, KeyExtractor, MultiExtractor, NullImplementation.NullValueExtractor, PartitionedJCacheStatistics.CacheStatisticsExtractor, PofExtractor, PropertySet, ReflectionExtractor, ScriptValueExtractor, 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 Details

    • 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.
      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

    • forMethod

      static <T, E> ValueExtractor<T,E> forMethod(Method method)
      Return a ValueExtractor for the specified Method.

      The method specified must have a non-void return type and no parameters.

      Type Parameters:
      T - the type of the value to extract from
      E - the type of value that will be extracted
      Parameters:
      method - the method to create a ValueExtractor for
      Returns:
      a ValueExtractor instance for the specified method
      Throws:
      IllegalArgumentException - if the method has one or more arguments or void return type
      Since:
      21.06

    • 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

      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:

    • 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