Class FieldScope
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.
-
Method Summary
Modifier and TypeMethodDescriptionabstract FieldScope
allowingFieldDescriptors
(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest) Returns aFieldScope
equivalent to this one, plus all fields matching the givenDescriptors.FieldDescriptor
s.abstract FieldScope
allowingFieldDescriptors
(Iterable<Descriptors.FieldDescriptor> fieldDescriptors) Returns aFieldScope
equivalent to this one, plus all fields matching the givenDescriptors.FieldDescriptor
s.abstract FieldScope
allowingFields
(int firstFieldNumber, int... rest) Returns aFieldScope
equivalent to this one, plus all fields defined by the given field numbers.abstract FieldScope
allowingFields
(Iterable<Integer> fieldNumbers) Returns aFieldScope
equivalent to this one, plus all fields defined by the given field numbers.abstract FieldScope
ignoringFieldDescriptors
(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest) Returns aFieldScope
equivalent to this one, minus all fields matching the givenDescriptors.FieldDescriptor
s.abstract FieldScope
ignoringFieldDescriptors
(Iterable<Descriptors.FieldDescriptor> fieldDescriptors) Returns aFieldScope
equivalent to this one, minus all fields defined by the given field numbers.abstract FieldScope
ignoringFields
(int firstFieldNumber, int... rest) Returns aFieldScope
equivalent to this one, minus all fields defined by the given field numbers.abstract FieldScope
ignoringFields
(Iterable<Integer> fieldNumbers) Returns aFieldScope
equivalent to this one, minus all fields defined by the given field numbers.
-
Method Details
-
ignoringFields
Returns aFieldScope
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 byProtoFluentAssertion.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 anotherYourMessage
somewhere within its subtree, aFieldScope ignoringFields(X)
will ignore field numberX
for all submessages of typeYourMessage
, as well as for the top-level message. -
ignoringFields
Returns aFieldScope
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 byProtoFluentAssertion.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 anotherYourMessage
somewhere within its subtree, aFieldScope ignoringFields(X)
will ignore field numberX
for all submessages of typeYourMessage
, as well as for the top-level message. -
ignoringFieldDescriptors
public abstract FieldScope ignoringFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest) Returns aFieldScope
equivalent to this one, minus all fields matching the givenDescriptors.FieldDescriptor
s.The
Descriptors.FieldDescriptor
s are not validated, as that would require scanning the entire protobuf schema recursively from this message type. If aDescriptors.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 typeFooMessage
. -
ignoringFieldDescriptors
public abstract FieldScope ignoringFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors) Returns aFieldScope
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 aDescriptors.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 typeFooMessage
. -
allowingFields
Returns aFieldScope
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 byProtoFluentAssertion.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 anotherYourMessage
somewhere within its subtree, aFieldScope allowingFields(X)
will include field numberX
for all submessages of typeYourMessage
, as well as for the top-level message. -
allowingFields
Returns aFieldScope
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 byProtoFluentAssertion.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 anotherYourMessage
somewhere within its subtree, aFieldScope allowingFields(X)
will include field numberX
for all submessages of typeYourMessage
, as well as for the top-level message. -
allowingFieldDescriptors
public abstract FieldScope allowingFieldDescriptors(Descriptors.FieldDescriptor firstFieldDescriptor, Descriptors.FieldDescriptor... rest) Returns aFieldScope
equivalent to this one, plus all fields matching the givenDescriptors.FieldDescriptor
s.The
Descriptors.FieldDescriptor
s are not validated, as that would require scanning the entire protobuf schema from this message type. If aDescriptors.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 typeFooMessage
. -
allowingFieldDescriptors
public abstract FieldScope allowingFieldDescriptors(Iterable<Descriptors.FieldDescriptor> fieldDescriptors) Returns aFieldScope
equivalent to this one, plus all fields matching the givenDescriptors.FieldDescriptor
s.The
Descriptors.FieldDescriptor
s are not validated, as that would require scanning the entire protobuf schema from this message type. If aDescriptors.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 typeFooMessage
.
-