com.hazelcast.query.extractor

Class ValueExtractor<T,A>

java.lang.Object

com.hazelcast.query.extractor.ValueExtractor<T,A>

Type Parameters:

T - type of the target object to extract the value from

A - type of the extraction argument object passed to the extract() method

public abstract class ValueExtractor<T,A>
extends Object

Common superclass for all extractors that enable the user to define custom attributes and extract their values. The extraction logic may just extract the underlying value or group, reduce or transform it.

How to use a ValueExtractor?

First, extend this class and implement the @see com.hazelcast.query.extractor.ValueExtractor#extract method. Then, define a new custom attribute referencing the implemented extractor in the configuration of the map.

How to define a new custom attribute? MapAttributeConfig attributeConfig = new MapAttributeConfig(); extractorConfig.setName("currency"); extractorConfig.setExtractor("com.bank.CurrencyExtractor");

How to register the newly-defined attribute in a configuration of a Map? MapConfig mapConfig = (...); mapConfig.addMapAttributeConfig(attributeConfig); Extractors may be also defined in the XML configuration.

 < map name="trades">
 < attributes>
 < attribute extractor="com.bank.CurrencyExtractor">currency< /attribute>
 < /attributes>
 < /map>
 

Please, bear in mind that an extractor may not be added after a map has been instantiated. All extractors have to be defined upfront in the map's initial configuration.

A ValueExtractor may use a custom argument if it is specified in the query. The custom argument may be passed within the square brackets located after the name of the attribute that uses a ValueExtractor, like: customAttribute[argumentString]

Let's have a look at the following query: 'currency[incoming] == EUR' Let's assume that currency is an custom attribute that uses com.test.CurrencyExtractor for extraction. The string "incoming" is an argument that will be passed to the ArgumentParser during the extraction. The parser will parse the string according to the parser's custom logic and it will return a parsed object. The parsed object may be a single object, array, collection, etc. It's up to the ValueExtractor implementor's to understand the semantics of the parsed argument object.

Reflection-based extraction is the default mechanism - ValueExtractors are an alternative way of extracting attribute values from an object.

It is also possible to use a ValueExtractor with a Portable data format. In this case the target object passed to the extractor implements a ValueReader interface.

Constructor Summary

Constructors

Constructor and Description
ValueExtractor()

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	extract(T target, A argument, ValueCollector collector) Extracts a value from the given target object.

Methods inherited from class java.lang.Object

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

Constructor Detail

ValueExtractor

public ValueExtractor()

Method Detail

extract

public abstract void extract(T target,
           A argument,
           ValueCollector collector)

Extracts a value from the given target object.

The method does not return any value since the extracted value may be collected by the ValueCollector#collect method.

In order to return multiple results from a single extraction just invoke the ValueCollector#collect method multiple times, so that the collector collects all results.

If the extraction is executed for an Object that implements a Portable interface the target object passed to the extractor is an instance of a ValueReader enabling extraction from the Portable byte stream.

It sounds counter-intuitive, but a single extraction may return multiple values when arrays or collections are involved.

Let's have a look at the following data structure: class Motorbike { Wheel wheel[2]; }

class Wheel { String name; }

Let's assume that we want to extract the names of all wheels from a single motorbike object. Each motorbike has two wheels so there are two names too. In order to return both values from the extraction operation just collect them separately using the ValueCollector. Collecting multiple values in such a way allows operating on these multiple values as if they were single-values during the evaluation of the predicates.

Let's assume that we registered a custom extractor to under the name 'wheelName' and executed the following query: 'wheelName = front-wheel'.

The extraction may return up to two wheel names for each Motorbike since each Motorbike has up to two wheels. In such a case, it is enough if a single value evaluates the predicate's condition to true to return a match, so it will return a Motorbike if 'any' of the wheels matches the expression.

Parameters:

target - object to extract the value from. In case the target object implements Portable interface the target object passed to this method is an instance of a ValueReader.

argument - extraction argument

collector - collector of the extracted value(s)

See Also:

ValueCollector