public abstract class FieldScope extends Object
FieldScopes
for entry points to obtain a FieldScope
object.
A FieldScope
is similar in concept to a FieldMask
, which is an explicitly
enumerated set of specific field paths. A FieldScope is more general, allowing for the
description of arbitrary classes of specific field paths to be included or excluded from its
definition. For example, given a large protocol buffer with many field definitions, and a single
string field named 'x', it is arduous to specify "All fields except 'x'" as a FieldMask
.
With a FieldScope
, it is simply FieldScopes.ignoringFields(MyMessage.X_FIELD_NUMBER)
.
All inclusion and exclusion operations on message-type fields are recursive, but may be
overridden by subsequent operations. In this way, a complex FieldScope
such as:
FieldScopes.ignoringFields(A.B_FIELD_NUMBER)
.allowingFieldDescriptors(B.getDescriptor().findFieldByName("flag"))
...will match all fields on A, except fields on the message type B, but including B's flag field.
Thus, two messages of type A will compare equal even if their sub messages of type B are
completely different, so long as the 'flag' fields for each B matches. Because of this, method
ordering matters. Generally, exclusions should come after inclusions.
FieldScope
s are not designed to be compact or efficient, trading flexibility of use
for runtime efficiency, generally composing themselves as recursive structures. For this reason,
it is not recommended to use FieldScope
in production code. Prefer to use proper FieldMask
s, directly in production code.
Modifier and Type | Method and Description |
---|---|
abstract FieldScope |
allowingFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor,
Descriptors.FieldDescriptor... rest)
Returns a
FieldScope equivalent to this one, plus all fields matching the given Descriptors.FieldDescriptor s. |
abstract FieldScope |
allowingFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
Returns a
FieldScope equivalent to this one, plus all fields matching the given Descriptors.FieldDescriptor s. |
abstract FieldScope |
allowingFields(int firstFieldNumber,
int... rest)
Returns a
FieldScope equivalent to this one, plus all fields defined by the given field
numbers. |
abstract FieldScope |
allowingFields(Iterable<Integer> fieldNumbers)
Returns a
FieldScope equivalent to this one, plus all fields defined by the given field
numbers. |
abstract FieldScope |
ignoringFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor,
Descriptors.FieldDescriptor... rest)
Returns a
FieldScope equivalent to this one, minus all fields matching the given Descriptors.FieldDescriptor s. |
abstract FieldScope |
ignoringFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
Returns a
FieldScope equivalent to this one, minus all fields defined by the given
field numbers. |
abstract FieldScope |
ignoringFields(int firstFieldNumber,
int... rest)
Returns a
FieldScope equivalent to this one, minus all fields defined by the given
field numbers. |
abstract FieldScope |
ignoringFields(Iterable<Integer> fieldNumbers)
Returns a
FieldScope equivalent to this one, minus all fields defined by the given
field numbers. |
public abstract FieldScope ignoringFields(int firstFieldNumber, int... rest)
FieldScope
equivalent to this one, minus all fields defined by the given
field numbers.
Validation of the field numbers is performed when the FieldScope
is invoked
(typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)
). A runtime exception will occur if bad
field numbers are encountered.
The field numbers are ignored recursively on this type. That is, if YourMessage
contains another YourMessage
somewhere within its subtree, a FieldScope
ignoringFields(X)
will ignore field number X
for all submessages of type YourMessage
, as well as for the top-level message.
public abstract FieldScope ignoringFields(Iterable<Integer> fieldNumbers)
FieldScope
equivalent to this one, minus all fields defined by the given
field numbers.
Validation of the field numbers is performed when the FieldScope
is invoked
(typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)
). A runtime exception will occur if bad
field numbers are encountered.
The field numbers are ignored recursively on this type. That is, if YourMessage
contains another YourMessage
somewhere within its subtree, a FieldScope
ignoringFields(X)
will ignore field number X
for all submessages of type YourMessage
, as well as for the top-level message.
public abstract FieldScope ignoringFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest)
FieldScope
equivalent to this one, minus all fields matching the given Descriptors.FieldDescriptor
s.
The Descriptors.FieldDescriptor
s are not validated, as that would require scanning the entire
protobuf schema recursively from this message type. If a Descriptors.FieldDescriptor
is provided
which refers to a field that is not part of this message, or any possible recursive
submessages, it is silently ignored.
The field descriptors are also ignored recursively on the message type. That is, if FooMessage.field_bar
is ignored, field_bar
will be ignored for all submessages of the
parent type of type FooMessage
.
public abstract FieldScope ignoringFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
FieldScope
equivalent to this one, minus all fields defined by the given
field numbers.
The Descriptors.FieldDescriptor
s are not validated, as that would require scanning the entire
protobuf schema recursively from this message type. If a Descriptors.FieldDescriptor
is provided
which refers to a field that is not part of this message, or any possible recursive
submessages, it is silently ignored.
The field descriptors are also ignored recursively on the message type. That is, if FooMessage.field_bar
is ignored, field_bar
will be ignored for all submessages of the
parent type of type FooMessage
.
public abstract FieldScope allowingFields(int firstFieldNumber, int... rest)
FieldScope
equivalent to this one, plus all fields defined by the given field
numbers.
Validation of the field numbers is performed when the FieldScope
is invoked
(typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)
). A runtime exception will occur if bad
field numbers are encountered.
The field numbers are included recursively on this type. That is, if YourMessage
contains another YourMessage
somewhere within its subtree, a FieldScope
allowingFields(X)
will include field number X
for all submessages of type YourMessage
, as well as for the top-level message.
public abstract FieldScope allowingFields(Iterable<Integer> fieldNumbers)
FieldScope
equivalent to this one, plus all fields defined by the given field
numbers.
Validation of the field numbers is performed when the FieldScope
is invoked
(typically by ProtoFluentAssertion.isEqualTo(com.google.protobuf.Message)
). A runtime exception will occur if bad
field numbers are encountered.
The field numbers are included recursively on this type. That is, if YourMessage
contains another YourMessage
somewhere within its subtree, a FieldScope
allowingFields(X)
will include field number X
for all submessages of type YourMessage
, as well as for the top-level message.
public abstract FieldScope allowingFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest)
FieldScope
equivalent to this one, plus all fields matching the given Descriptors.FieldDescriptor
s.
The Descriptors.FieldDescriptor
s are not validated, as that would require scanning the entire
protobuf schema from this message type. If a Descriptors.FieldDescriptor
is provided which refers
to a field that is not part of this message, or any possible recursive submessages, it is
silently ignored.
The field descriptors are also included recursively on the message type. That is, if FooMessage.field_bar
is included, field_bar
will be included for all submessages of
the parent type of type FooMessage
.
public abstract FieldScope allowingFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors)
FieldScope
equivalent to this one, plus all fields matching the given Descriptors.FieldDescriptor
s.
The Descriptors.FieldDescriptor
s are not validated, as that would require scanning the entire
protobuf schema from this message type. If a Descriptors.FieldDescriptor
is provided which refers
to a field that is not part of this message, or any possible recursive submessages, it is
silently ignored.
The field descriptors are also included recursively on the message type. That is, if FooMessage.field_bar
is included, field_bar
will be included for all submessages of
the parent type of type FooMessage
.
Copyright © 2020. All rights reserved.