com.tangosol.util.filter

Class ArrayFilter

java.lang.Object

com.tangosol.util.Base

com.tangosol.util.BitHelper

com.tangosol.util.ExternalizableHelper

com.tangosol.util.filter.ArrayFilter

All Implemented Interfaces:

ExternalizableLite, PortableObject, Filter, EntryFilter, IndexAwareFilter, QueryRecorderFilter, Serializable

Direct Known Subclasses:

AllFilter, AnyFilter, XorFilter

public abstract class ArrayFilter
extends ExternalizableHelper
implements EntryFilter, IndexAwareFilter, QueryRecorderFilter, ExternalizableLite, PortableObject

Filter which is a logical operator of a filter array.

Author:

cp/gg 2002.11.01

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static class	ArrayFilter.WeightedFilter A thin wrapper around a Filter allowing for sorting the filters according to their effectiveness.

Nested classes/interfaces inherited from class com.tangosol.util.ExternalizableHelper

ExternalizableHelper.DecoratedMultiBufferReadBuffer, ExternalizableHelper.DefaultObjectStreamFactory, ExternalizableHelper.FormatAwareCompressor, ExternalizableHelper.IntDecoratedObject, ExternalizableHelper.Shielded, ExternalizableHelper.ShieldedDataOutputStream, ExternalizableHelper.ShieldedInputStream, ExternalizableHelper.ShieldedObjectOutputStream, ExternalizableHelper.ShieldedOutputStream, ExternalizableHelper.SimpleXmlBeanClassCache, ExternalizableHelper.Stats, ExternalizableHelper.XmlBeanClassCache

Nested classes/interfaces inherited from class com.tangosol.util.Base

Base.LoggingWriter, Base.StackFrame

Field Summary

Fields

Modifier and Type	Field and Description
protected Filter[]	m_aFilter The Filter array.
protected boolean	m_fPreserveOrder Flag indicating whether or not the filter order should be preserved.

Fields inherited from class com.tangosol.util.ExternalizableHelper

CONVERTER_FROM_BINARY, CONVERTER_STRIP_INTDECO, CONVERTER_TO_BINARY, DECO_APP_1, DECO_APP_2, DECO_APP_3, DECO_CUSTOM, DECO_EXPIRY, DECO_ID_MAX, DECO_ID_MIN, DECO_JCACHE, DECO_JCACHE_SYNTHETIC, DECO_MEMCACHED, DECO_PUSHREP, DECO_QUEUE_METADATA, DECO_RSVD_1, DECO_RSVD_2, DECO_STORE, DECO_TX, DECO_VALUE, DECO_WLS, EMPTY_BINARY_ARRAY, FMT_B_ARRAY, FMT_BIN_DECO, FMT_BIN_EXT_DECO, FMT_BINARY, FMT_BOOLEAN, FMT_BYTE, FMT_DECIMAL, FMT_DOUBLE, FMT_EXT, FMT_FLOAT, FMT_IDO, FMT_INT, FMT_INTEGER, FMT_LONG, FMT_NONE, FMT_NULL, FMT_OBJ_EXT, FMT_OBJ_SER, FMT_OPT, FMT_OPT_DOUBLE, FMT_OPT_INT, FMT_OPT_LONG, FMT_SHORT, FMT_STRING, FMT_UNKNOWN, FMT_XML_BEAN, FMT_XML_SER, FORCE_RESOLVING_STREAMS, MAX_DECO_HEADER_BYTES, PROPERTY_CONFIG, s_streamfactory, TRINT_DOMAIN_SPAN, TRINT_MAX_VALUE, TRINT_MAX_VARIANCE, USE_POF_STREAMS, USE_XMLBEAN_CLASS_CACHE, XMLBEAN_CLASS_CACHE

Fields inherited from class com.tangosol.util.Base

LOG_ALWAYS, LOG_DEBUG, LOG_ERR, LOG_INFO, LOG_MAX, LOG_MIN, LOG_QUIET, LOG_WARN, POWER_0, POWER_G, POWER_K, POWER_M, POWER_T, UNIT_D, UNIT_H, UNIT_M, UNIT_MS, UNIT_NS, UNIT_S, UNIT_US

Constructor Summary

Constructors

Constructor and Description
ArrayFilter() Default constructor (necessary for the ExternalizableLite interface).
ArrayFilter(Filter[] aFilter) Construct a logical filter that applies a binary operator to a filter array.

Method Summary

Modifier and Type	Method and Description
protected Filter	applyFilter(Filter filter, int iFilter, Map mapIndexes, Set setKeys, QueryContext ctx, QueryRecord.PartialResult.TraceStep step) Apply the specified IndexAwareFilter to the specified keySet.
Filter	applyIndex(Map mapIndexes, Set setKeys) Filter remaining keys using a Map of available indexes.
protected abstract Filter	applyIndex(Map mapIndexes, Set setKeys, QueryContext ctx, QueryRecord.PartialResult.TraceStep step) Apply the specified IndexAwareFilter to the specified keySet.
boolean	equals(Object o) Compare the ArrayFilter with another object to determine equality.
boolean	evaluateEntry(Map.Entry entry) Apply the test to a Map Entry.
protected abstract boolean	evaluateEntry(Map.Entry entry, QueryContext ctx, QueryRecord.PartialResult.TraceStep step) Check if the given entry passes the filter's evaluation.
protected boolean	evaluateFilter(Filter filter, Map.Entry entry, QueryContext ctx, QueryRecord.PartialResult.TraceStep step) Check if the given entry passes the given filter's evaluation.
void	explain(QueryContext ctx, QueryRecord.PartialResult.ExplainStep step, Set setKeys) Record the projected query execution cost by this filter.
Filter[]	getFilters() Obtain the Filter array.
int	hashCode() Determine a hash value for the ArrayFilter object according to the general Object.hashCode() contract.
void	honorOrder() Ensure that the order of underlying filters is preserved by the applyIndex(java.util.Map, java.util.Set) and evaluateEntry(java.util.Map.Entry) implementations.
protected void	optimizeFilterOrder(Map mapIndexes, Set setKeys) Sort all the participating filters according to their effectiveness.
void	readExternal(DataInput in) Restore the contents of this object by loading the object's state from the passed DataInput object.
void	readExternal(PofReader in) Restore the contents of a user type instance by reading its state using the specified PofReader object.
String	toString() Return a human-readable description for this Filter.
boolean	trace(QueryContext ctx, QueryRecord.PartialResult.TraceStep step, Map.Entry entry) Evaluate the specified entry against this filter and record the evaluation cost on the given step of the QueryRecord.
Filter	trace(QueryContext ctx, QueryRecord.PartialResult.TraceStep step, Set setKeys) Filter the given keys using available indexes and record the cost of execution on the given step of the QueryRecord.
void	writeExternal(DataOutput out) Save the contents of this object by storing the object's state into the passed DataOutput object.
void	writeExternal(PofWriter out) Save the contents of a POF user type instance by writing its state using the specified PofWriter object.

Methods inherited from class com.tangosol.util.ExternalizableHelper

asBinary, calculatePackedLength, calculatePackedLength, checkObjectInputFilter, convertUTF, decodeExpiry, decorate, decorate, decorate, decorate, decorate, decorateBinary, encodeExpiry, ensureSerializer, extractIntDecoration, fromBinary, fromBinary, fromBinary, fromBinary, fromBinary, fromBinary, fromByteArray, fromByteArray, getClass, getDecoration, getDecoration, getDecorations, getDeltaCompressor, getInputStream, getNewObjectInput, getObjectInput, getObjectOutput, getObjectStreamFactory, getOutputStream, getShieldedOutputStream, getStreamFormat, getUndecorated, getUndecorated, isDecorated, isDecorated, isIntDecorated, isIntDecorated, isResolving, isSerializable, isSerializerCompatible, isVersionCompatible, isVersionCompatible, loadClass, loadResource, main, makeTrint, readBigDecimal, readBigInteger, readBooleanArray, readByteArray, readCollection, readDate, readDoubleArray, readExternalizableLite, readExternalizableLite, readFloatArray, readInt, readInt, readIntArray2d, readLong, readLong, readMap, readMap, readObject, readObject, readSafeUTF, readSafeUTF, readSerializable, readSerializable, readStringArray, readTime, readTimestamp, readTrint, readUnsignedTrint, readUTF, readXmlBean, readXmlSerializable, readXmlSerializable, realize, removeIntDecoration, removeIntDecoration, replace, reportIncompatibleSerializers, setObjectStreamFactory, toBinary, toBinary, toByteArray, toByteArray, toByteArray, toLiteBinary, toLong, undecorate, undecorate, validateBufferSize, writeBigDecimal, writeBigInteger, writeBooleanArray, writeByteArray, writeCollection, writeDate, writeDoubleArray, writeExternalizableLite, writeFloatArray, writeInt, writeInt, writeIntArray2d, writeLong, writeLong, writeMap, writeObject, writeSafeUTF, writeSafeUTF, writeSerializable, writeStringArray, writeTime, writeTimestamp, writeTrint, writeTrint, writeUTF, writeXmlBean, writeXmlSerializable

Methods inherited from class com.tangosol.util.BitHelper

countBits, countBits, countBits, indexOfLSB, indexOfLSB, indexOfLSB, indexOfMSB, indexOfMSB, indexOfMSB, rotateLeft, rotateLeft, rotateLeft, rotateRight, rotateRight, rotateRight, toBitString, toBitString, toBitString, toBytes, toBytes, toBytes, toBytes, toInt, toInt, toLong

Methods inherited from class com.tangosol.util.Base

azzert, azzert, azzert, azzertFailed, breakLines, breakLines, capitalize, checkNotEmpty, checkNotNull, checkRange, computeSafeWaitTime, decimalValue, dup, dup, ensureBigDecimal, ensureClassLoader, ensureRuntimeException, ensureRuntimeException, equals, equalsDeep, err, err, err, err, err, escape, formatDateTime, getCallerStackFrame, getCommonMonitor, getCommonMonitor, getCommonMonitor, getContextClassLoader, getContextClassLoader, getDeepMessage, getErr, getLastSafeTimeMillis, getLog, getMaxDecDigits, getMaxHexDigits, getOriginalException, getOut, getProcessRandom, getRandom, getRandomBinary, getRandomBinary, getRandomString, getSafeTimeMillis, getStackFrame, getStackFrames, getStackTrace, getStackTrace, getThreadFactory, getTimeZone, getUpTimeMillis, hashCode, hexValue, indentString, indentString, isDecimal, isHex, isLogEcho, isOctal, log, log, log, log, log, makeInteger, makeLong, makeThread, mod, mod, octalValue, out, out, out, out, out, pad, parseBandwidth, parseBandwidth, parseDelimitedString, parseHex, parseHex, parseMemorySize, parseMemorySize, parsePercentage, parseTime, parseTime, parseTimeNanos, parseTimeNanos, printStackTrace, randomize, randomize, randomize, randomize, read, read, read, read, read, read, read, replace, setErr, setLog, setLogEcho, setOut, sleep, toBandwidthString, toBandwidthString, toCharEscape, toCrc, toCrc, toCrc, toCrc, toCrc, toDecString, toDelimitedString, toDelimitedString, toDelimitedString, toDelimitedString, toHex, toHex, toHexDump, toHexEscape, toHexEscape, toHexEscape, toHexEscape, toHexString, toMemorySizeString, toMemorySizeString, toQuotedCharEscape, toQuotedStringEscape, toSqlString, toString, toString, toStringEscape, toUnicodeEscape, trace, trace, trace, trace, trace, trace, trace, trace, trace, truncateString, truncateString, wait

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.tangosol.util.filter.IndexAwareFilter

calculateEffectiveness

Methods inherited from interface com.tangosol.util.Filter

and, asLimitFilter, associatedWith, evaluate, forKeys, forPartitions, or, xor

Field Detail

m_aFilter

protected Filter[] m_aFilter

The Filter array.

m_fPreserveOrder

protected boolean m_fPreserveOrder

Flag indicating whether or not the filter order should be preserved.

Since:

Coherence 12.2.1

Constructor Detail

ArrayFilter

public ArrayFilter()

Default constructor (necessary for the ExternalizableLite interface).

ArrayFilter

public ArrayFilter(Filter[] aFilter)

Construct a logical filter that applies a binary operator to a filter array. The result is defined as:

aFilter[0] <op> aFilter[1] ... <op> aFilter[n]

Parameters:

aFilter - the filter array

Method Detail

evaluateEntry

public boolean evaluateEntry(Map.Entry entry)

Apply the test to a Map Entry.

Specified by:

evaluateEntry in interface EntryFilter

Parameters:

entry - the Map Entry to evaluate; never null

Returns:

true if the test passes, false otherwise

applyIndex

public Filter applyIndex(Map mapIndexes,
                         Set setKeys)

Filter remaining keys using a Map of available indexes.

The filter is responsible for removing all keys from the passed set of keys that the applicable indexes can prove should be filtered. If the filter does not fully evaluate the remaining keys using just the index information, it must return a filter (which may be an EntryFilter) that can complete the task using an iterating implementation. If, on the other hand, the filter does fully evaluate the remaining keys using just the index information, then it should return null to indicate that no further filtering is necessary.

Specified by:

applyIndex in interface IndexAwareFilter

Parameters:

mapIndexes - the available MapIndex objects keyed by the related ValueExtractor; read-only

setKeys - the mutable set of keys that remain to be filtered

Returns:

a Filter object (which may be an EntryFilter) that can be used to process the remaining keys, or null if no additional filter processing is necessary

explain

public void explain(QueryContext ctx,
                    QueryRecord.PartialResult.ExplainStep step,
                    Set setKeys)

Record the projected query execution cost by this filter.

This method is expected to record the order of execution and estimated cost of applying corresponding indexes in the given step without actually applying any indexes or evaluating entries.

Specified by:

explain in interface QueryRecorderFilter

Parameters:

ctx - the query context

step - the step used to record the estimated execution cost

setKeys - the set of keys that would be filtered

trace

public Filter trace(QueryContext ctx,
                    QueryRecord.PartialResult.TraceStep step,
                    Set setKeys)

Filter the given keys using available indexes and record the cost of execution on the given step of the QueryRecord.

This method should record the size of the given key set before and after applying corresponding indexes using QueryRecord.PartialResult.RecordableStep.recordPreFilterKeys(int) and QueryRecord.PartialResult.TraceStep.recordPostFilterKeys(int) as well as the corresponding execution time using the QueryRecord.PartialResult.TraceStep.recordDuration(long) method.

This method is only called if the filter is an IndexAwareFilter and its implementations should explicitly call applyIndex() to actually perform the query. Additionally, this method should return the filter object (if any) returned by the applyIndex() call.

Specified by:

trace in interface QueryRecorderFilter

Parameters:

ctx - the query context

step - the step used to record the execution cost

setKeys - the mutable set of keys that remain to be filtered

Returns:

the filter returned from IndexAwareFilter.applyIndex(Map, Set)

trace

public boolean trace(QueryContext ctx,
                     QueryRecord.PartialResult.TraceStep step,
                     Map.Entry entry)

Evaluate the specified entry against this filter and record the evaluation cost on the given step of the QueryRecord.

This method should record the corresponding latencies using QueryRecord.PartialResult.TraceStep.recordDuration(long).

Implementations are responsible for explicitly calling evaluateEntry() method to perform the actual entry evaluation. Additionally, this method should return the result of the evaluateEntry call.

Specified by:

trace in interface QueryRecorderFilter

Parameters:

ctx - the context

step - the step used to record the evaluation cost

entry - the entry to evaluate

Returns:

the result returned from EntryFilter.evaluateEntry(Map.Entry)

applyIndex

protected abstract Filter applyIndex(Map mapIndexes,
                                     Set setKeys,
                                     QueryContext ctx,
                                     QueryRecord.PartialResult.TraceStep step)

Apply the specified IndexAwareFilter to the specified keySet. Record the actual cost of execution for each of the participating filters if a query context is provided.

Parameters:

mapIndexes - the available MapIndex objects keyed by the related ValueExtractor; read-only

setKeys - the set of keys that would be filtered

ctx - the query ctx; may be null

step - the step used to record the execution cost

Returns:

a Filter object that can be used to process the remaining keys, or null if no additional filter processing is necessary

evaluateEntry

protected abstract boolean evaluateEntry(Map.Entry entry,
                                         QueryContext ctx,
                                         QueryRecord.PartialResult.TraceStep step)

Check if the given entry passes the filter's evaluation. Record the actual cost of execution for each of the participating filters if a query context is provided.

Parameters:

entry - a key value pair to filter

ctx - the query ctx; may be null

step - the step used to record the execution cost

Returns:

true if the entry passes the filter, false otherwise

getFilters

public Filter[] getFilters()

Obtain the Filter array.

Returns:

the Filter array

honorOrder

public void honorOrder()

Ensure that the order of underlying filters is preserved by the applyIndex(java.util.Map, java.util.Set) and evaluateEntry(java.util.Map.Entry) implementations.

optimizeFilterOrder

protected void optimizeFilterOrder(Map mapIndexes,
                                   Set setKeys)

Sort all the participating filters according to their effectiveness.

Parameters:

mapIndexes - the available MapIndex objects keyed by the related ValueExtractor; read-only

setKeys - the set of keys that will be filtered; read-only

applyFilter

protected Filter applyFilter(Filter filter,
                             int iFilter,
                             Map mapIndexes,
                             Set setKeys,
                             QueryContext ctx,
                             QueryRecord.PartialResult.TraceStep step)

Apply the specified IndexAwareFilter to the specified keySet. Record the actual cost of execution if a query context is provided.

Parameters:

filter - the IndexAwareFilter to apply an index to

iFilter - the index of the given filter in this filter's array of indexes

mapIndexes - the available MapIndex objects keyed by the related ValueExtractor; read-only

setKeys - the mutable set of keys that remain to be filtered

ctx - the query ctx; may be null

step - the step used to record the execution cost

Returns:

a Filter object that can be used to process the remaining keys, or null if no additional filter processing is necessary

evaluateFilter

protected boolean evaluateFilter(Filter filter,
                                 Map.Entry entry,
                                 QueryContext ctx,
                                 QueryRecord.PartialResult.TraceStep step)

Check if the given entry passes the given filter's evaluation. Record the actual cost of execution if a query context is provided.

Parameters:

filter - the Filter to use to evaluate the entry

entry - a key value pair to filter

ctx - the query ctx; may be null

step - the step used to record the execution cost

Returns:

true if the entry passes the filter, false otherwise

equals

public boolean equals(Object o)

Compare the ArrayFilter with another object to determine equality. Two ArrayFilter objects are considered equal iff they belong to exactly the same class and their filter arrays are equal.

Overrides:

equals in class Object

Returns:

true iff this ArrayFilter and the passed object are equivalent ArrayFilters

hashCode

public int hashCode()

Determine a hash value for the ArrayFilter object according to the general Object.hashCode() contract.

Overrides:

hashCode in class Object

Returns:

an integer hash value for this ArrayFilter object

toString

public String toString()

Return a human-readable description for this Filter.

Overrides:

toString in class Object

Returns:

a String description of the Filter

readExternal

public void readExternal(DataInput in)
                  throws IOException

Restore the contents of this object by loading the object's state from the passed DataInput object.

Specified by:

readExternal in interface ExternalizableLite

Parameters:

in - the DataInput stream to read data from in order to restore the state of this object

Throws:

IOException - if an I/O exception occurs

NotActiveException - if the object is not in its initial state, and therefore cannot be deserialized into

writeExternal

public void writeExternal(DataOutput out)
                   throws IOException

Save the contents of this object by storing the object's state into the passed DataOutput object.

Specified by:

writeExternal in interface ExternalizableLite

Parameters:

out - the DataOutput stream to write the state of this object to

Throws:

IOException - if an I/O exception occurs

readExternal

public void readExternal(PofReader in)
                  throws IOException

Restore the contents of a user type instance by reading its state using the specified PofReader object.

Specified by:

readExternal in interface PortableObject

Parameters:

in - the PofReader from which to read the object's state

Throws:

IOException - if an I/O error occurs

writeExternal

public void writeExternal(PofWriter out)
                   throws IOException

Save the contents of a POF user type instance by writing its state using the specified PofWriter object.

Specified by:

writeExternal in interface PortableObject

Parameters:

out - the PofWriter to which to write the object's state

Throws:

IOException - if an I/O error occurs