com.apple.foundationdb.record.metadata.expressions

Class FieldKeyExpression

java.lang.Object

com.apple.foundationdb.record.metadata.expressions.BaseKeyExpression

com.apple.foundationdb.record.metadata.expressions.FieldKeyExpression

All Implemented Interfaces:

AtomKeyExpression, KeyExpression, KeyExpressionWithoutChildren, PlanHashable

@API(value=MAINTAINED)
public class FieldKeyExpression
extends BaseKeyExpression
implements AtomKeyExpression, KeyExpressionWithoutChildren

Take keys from a record field. If fieldName is a repeated field, then FanType.Concatenate turns all the field values into a single Key.Evaluated. If FanType.FanOut, there is one (singleton) Key.Evaluated for each repeated value. If this is evaluated on the null record, then it will the same value as if it were evaluated on a record where the field is either unset (in the case of scalar fields) or empty (in the case of repeated fields). In particular, if FanType.None, then this returns a single Key.Evaluated containing null; if FanType.FanOut, then this returns no Key.Evaluateds; and if FanType.Concatenate, then this returns a single Key.Evaluated containing the empty list.

Nested Class Summary

Nested classes/interfaces inherited from class com.apple.foundationdb.record.metadata.expressions.BaseKeyExpression

BaseKeyExpression.IllegalSubKeyException, BaseKeyExpression.UnsplittableKeyExpressionException

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.metadata.expressions.KeyExpression

KeyExpression.DeserializationException, KeyExpression.FanType, KeyExpression.InvalidExpressionException, KeyExpression.InvalidResultException, KeyExpression.NoSuchArgumentException, KeyExpression.SerializationException

Constructor Summary

Constructors

Constructor and Description
FieldKeyExpression(RecordMetaDataProto.Field field)
FieldKeyExpression(String fieldName, KeyExpression.FanType fanType, Key.Evaluated.NullStandin nullStandin)

Method Summary

Modifier and Type	Method and Description
boolean	createsDuplicates() This states whether the given expression type is capable of evaluating more to more than one value when applied to a single record.
boolean	equals(Object o)
boolean	equalsAtomic(AtomKeyExpression other)
<M extends Message> List<Key.Evaluated>	evaluateMessage(FDBRecord<M> record, Message message) Evaluate this expression against a record or a Protobuf message.
int	getColumnSize() Returns the number of items in each KeyValue that will be returned.
Descriptors.Descriptor	getDescriptor(Descriptors.Descriptor parentDescriptor)
KeyExpression.FanType	getFanType()
String	getFieldName()
Key.Evaluated.NullStandin	getNullStandin()
GroupingKeyExpression	groupBy(KeyExpression groupByFirst, KeyExpression... groupByRest)
int	hashCode()
NestingKeyExpression	nest(KeyExpression child) Nest another expression inside this one.
NestingKeyExpression	nest(KeyExpression first, KeyExpression second, KeyExpression... rest) Shorthand for nest(concat(first, second, rest)).
NestingKeyExpression	nest(String fieldName) Nest a single scalar field inside of this one.
NestingKeyExpression	nest(String fieldName, KeyExpression.FanType fanType) Nest a single field inside of this one, optionally setting the handling for a repeated field.
KeyExpression	normalizeForPlanner(Source source, List<String> fieldNamePrefix) Normalize this key expression into another key expression that pushes all nesting and fan-out to ElementKeyExpressions at the leaves.
int	planHash() Return a hash similar to hashCode, but with the additional guarantee that is is stable across JVMs.
SplitKeyExpression	split(int splitSize)
RecordMetaDataProto.KeyExpression	toKeyExpression()
RecordMetaDataProto.Field	toProto()
String	toString()
GroupingKeyExpression	ungrouped() Get this field as a group without any grouping keys.
List<Descriptors.FieldDescriptor>	validate(Descriptors.Descriptor parentDescriptor) Validate this expression against a given record type descriptor.
List<Descriptors.FieldDescriptor>	validate(Descriptors.Descriptor parentDescriptor, boolean allowMessageType)
void	validate(Descriptors.Descriptor parentDescriptor, Descriptors.FieldDescriptor fieldDescriptor, boolean allowMessageType)

Methods inherited from class com.apple.foundationdb.record.metadata.expressions.BaseKeyExpression

getSubKey, getSubKeyImpl, isPrefixKey

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.apple.foundationdb.record.metadata.expressions.KeyExpression

evaluate, evaluateSingleton, flattenForPlanner, fromProto, getSubKey, hasProperInterfaces, hasRecordTypeKey, isPrefixKey, normalizeKeyForPositions, versionColumns

Methods inherited from interface com.apple.foundationdb.record.PlanHashable

combineHashes, iterablePlanHash, objectPlanHash, objectsPlanHash, planHash, planHash, planHashUnordered, stringHashUnordered

Constructor Detail

FieldKeyExpression

public FieldKeyExpression(@Nonnull
                          String fieldName,
                          @Nonnull
                          KeyExpression.FanType fanType,
                          @Nonnull
                          Key.Evaluated.NullStandin nullStandin)

FieldKeyExpression

public FieldKeyExpression(@Nonnull
                          RecordMetaDataProto.Field field)
                   throws KeyExpression.DeserializationException

Throws:

KeyExpression.DeserializationException

Method Detail

validate

public List<Descriptors.FieldDescriptor> validate(@Nonnull
                                                  Descriptors.Descriptor parentDescriptor)

Description copied from interface: KeyExpression

Validate this expression against a given record type descriptor.

Specified by:

validate in interface KeyExpression

Parameters:

parentDescriptor - the descriptor for the record type or submessage

Returns:

a list of fields that this key applies to

validate

public List<Descriptors.FieldDescriptor> validate(@Nonnull
                                                  Descriptors.Descriptor parentDescriptor,
                                                  boolean allowMessageType)

validate

public void validate(@Nonnull
                     Descriptors.Descriptor parentDescriptor,
                     Descriptors.FieldDescriptor fieldDescriptor,
                     boolean allowMessageType)

evaluateMessage

@Nonnull
public <M extends Message> List<Key.Evaluated> evaluateMessage(@Nullable
                                                                        FDBRecord<M> record,
                                                                        @Nullable
                                                                        Message message)

Description copied from interface: KeyExpression

Evaluate this expression against a record or a Protobuf message. The message might be the Protobuf form of a record or a piece of that record. If the key expression is meaningful against a subrecord, it should evaluate against the message. Otherwise, it should evaluate against the record and ignore what part of that record is being considered. There should not be any reason to call this method outside of the implementation of another evaluateMessage. Under ordinary circumstances, if record is null, then message will be null. Otherwise, message will be record.getRecord() or some submessage of that, possibly null if the corresponding field is missing.

Specified by:

evaluateMessage in interface KeyExpression

Type Parameters:

M - the type of record

Parameters:

record - the record

message - the Protobuf message to evaluate against

Returns:

the evaluated keys for the given record

See Also:

KeyExpression.evaluate(com.apple.foundationdb.record.provider.foundationdb.FDBRecord<M>)

createsDuplicates

public boolean createsDuplicates()

Description copied from interface: KeyExpression

This states whether the given expression type is capable of evaluating more to more than one value when applied to a single record. In practice, this can happen if this expression is evaluated on a repeated field with FanType.FanOut set (either directly or indirectly).

Specified by:

createsDuplicates in interface KeyExpression

Returns:

true if this expression can evaluate to multiple values and false otherwise

getColumnSize

public int getColumnSize()

Description copied from interface: KeyExpression

Returns the number of items in each KeyValue that will be returned. For key expressions that support KeyExpression.FanType.Concatenate, this will the count of non-nested lists, i.e. this will be value of evaluate(r).get(i).toList().size() for any i or r.

Specified by:

getColumnSize in interface KeyExpression

Returns:

the number of elements that will be produced for every key

toProto

@Nonnull
public RecordMetaDataProto.Field toProto()
                                           throws KeyExpression.SerializationException

Specified by:

toProto in interface KeyExpression

Throws:

KeyExpression.SerializationException

toKeyExpression

@Nonnull
public RecordMetaDataProto.KeyExpression toKeyExpression()

Specified by:

toKeyExpression in interface KeyExpression

normalizeForPlanner

@Nonnull
public KeyExpression normalizeForPlanner(@Nonnull
                                                  Source source,
                                                  @Nonnull
                                                  List<String> fieldNamePrefix)

Description copied from interface: KeyExpression

Normalize this key expression into another key expression that pushes all nesting and fan-out to ElementKeyExpressions at the leaves.

By default, a key expression is a complicated nested structure that can be difficult to work with. This method pushes much of the complexity, including nested structures and fan-out of repeated fields, to special key expressions that track these relationship using the Source abstraction. This pre-processing makes planning nested and repeated structures much simpler.

This normalization process requires tracking some state since the name of a nested field is available only at the relevant FieldKeyExpression, but that information is necessary to construct the ElementKeyExpression at the leaves of the sub-tree rooted at the NestingKeyExpression. This extra information is tracked in the fieldNamePrefix.

Specified by:

normalizeForPlanner in interface KeyExpression

Parameters:

source - the source representing the input stream of the key expression

fieldNamePrefix - the (non-repeated) field names on the path from the most recent source to this part of the key expression

Returns:

a new key expression that has only ElementKeyExpressions at its leaves

getFieldName

@Nonnull
public String getFieldName()

nest

@Nonnull
public NestingKeyExpression nest(@Nonnull
                                          String fieldName)

Nest a single scalar field inside of this one. Shorthand to nest(field(fieldName))

Parameters:

fieldName - the name of the nested field. This is contextual, there is no need to use the full path.

Returns:

a new expression that will get the value from the value of the given field for each value of this field.

nest

@Nonnull
public NestingKeyExpression nest(@Nonnull
                                          String fieldName,
                                          @Nonnull
                                          KeyExpression.FanType fanType)

Nest a single field inside of this one, optionally setting the handling for a repeated field. Shorthand to nest(field(fieldName, fanType))

Parameters:

fieldName - the name of the nested field

fanType - how to handle the nested field repeated state

Returns:

a new key that will get all of the values from the value of the given field within this field

nest

@Nonnull
public NestingKeyExpression nest(@Nonnull
                                          KeyExpression first,
                                          @Nonnull
                                          KeyExpression second,
                                          @Nonnull
                                          KeyExpression... rest)

Shorthand for nest(concat(first, second, rest)).

Parameters:

first - the first child expression to use

second - the second child expression to use

rest - this supports any number children (at least 2), this is the rest of them

Returns:

a new key that will get all of the values from the value of the given field within this field

nest

@Nonnull
public NestingKeyExpression nest(@Nonnull
                                          KeyExpression child)

Nest another expression inside this one. That one will be evaluated for each value of this field in the context of this field. This field must be pointed to a Message. The child also has no access to the parts of the record outside of this field value. If this field is repeated with FanOut, there will be one index entry for each value of this field.

Parameters:

child - a child expression to be evaluated on the message that this field has

Returns:

a new expression for evaluating this complicated nesting

Throws:

InvalidExpressionException - if this field is of concatenate type At least for now.

ungrouped

@Nonnull
public GroupingKeyExpression ungrouped()

Get this field as a group without any grouping keys.

Returns:

this field without any grouping keys

groupBy

@Nonnull
public GroupingKeyExpression groupBy(@Nonnull
                                              KeyExpression groupByFirst,
                                              @Nonnull
                                              KeyExpression... groupByRest)

split

@Nonnull
public SplitKeyExpression split(int splitSize)

getDescriptor

@Nonnull
public Descriptors.Descriptor getDescriptor(@Nonnull
                                                     Descriptors.Descriptor parentDescriptor)

getFanType

@Nonnull
public KeyExpression.FanType getFanType()

getNullStandin

@Nonnull
public Key.Evaluated.NullStandin getNullStandin()

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

planHash

public int planHash()

Description copied from interface: PlanHashable

Return a hash similar to hashCode, but with the additional guarantee that is is stable across JVMs.

Specified by:

planHash in interface PlanHashable

Returns:

a stable hash code

equalsAtomic

public boolean equalsAtomic(AtomKeyExpression other)

Specified by:

equalsAtomic in interface AtomKeyExpression