SingleFieldBuilderimplements a structure that a protocol message uses to hold a single
field of another protocol message. It supports the classical use case of setting an immutableMessageas the value of the field and is highly optimized around this.
It also supports the additional use case of setting aMessage.Builderas the field and
deferring conversion of thatBuilderto an immutableMessage. In this way, it's
possible to maintain a tree ofBuilder's that acts as a fully read/write data structure. Logically, one can think of a tree of builders as converting the entire tree to messages when
build is called on the root or when any method is called that desires a Message instead of a
Builder. In terms of the implementation, theSingleFieldBuilderandRepeatedFieldBuilderclasses cache messages that were created so that messages only need to be
created when some change occurred in its builder or a builder for one of its descendants.
Gets a builder for the field. If no builder has been created yet, a builder is created on
demand by callingMessage#toBuilder.
Returns
Type
Description
BType
The builder for the field
getMessage()
publicMTypegetMessage()
Get the message for the field. If the message is currently stored as aBuilder, it is
converted to aMessageby callingMessage.Builder#buildPartialon it. If no
message has been set, returns the default instance of the message.
Returns
Type
Description
MType
the message for the field
getMessageOrBuilder()
publicITypegetMessageOrBuilder()
Gets the base class interface for the field. This may either be a builder or a message. It will
return whatever is more efficient.
Returns
Type
Description
IType
the message or builder for the field as the base class interface
markDirty()
publicvoidmarkDirty()
A builder becomes dirty whenever a field is modified -- including fields in nested builders
-- and becomes clean when build() is called. Thus, when a builder becomes dirty, all its
parents become dirty as well, and when it becomes clean, all its children become clean. The
dirtiness state is used to invalidate certain cached values.
To this end, a builder calls markDirty() on its parent whenever it transitions from clean
to dirty. The parent must propagate this call to its own parent, unless it was already dirty,
in which case the grandparent must necessarily already be dirty as well. The parent can only
transition back to "clean" after calling build() on all children.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Class SingleFieldBuilder<MType,BType,IType> (3.19.4)\n\n public class SingleFieldBuilder\u003cMType,BType,IType\u003e implements GeneratedMessage.BuilderParent\n\n`SingleFieldBuilder` implements a structure that a protocol message uses to hold a single\nfield of another protocol message. It supports the classical use case of setting an immutable\n[Message](/java/docs/reference/protobuf/latest/com.google.protobuf.Message) as the value of the field and is highly optimized around this.\n\nIt also supports the additional use case of setting a [Message.Builder](/java/docs/reference/protobuf/latest/com.google.protobuf.Message.Builder) as the field and\ndeferring conversion of that `Builder` to an immutable `Message`. In this way, it's\npossible to maintain a tree of `Builder`'s that acts as a fully read/write data structure.\n\n\nLogically, one can think of a tree of builders as converting the entire tree to messages when\nbuild is called on the root or when any method is called that desires a Message instead of a\nBuilder. In terms of the implementation, the `SingleFieldBuilder` and `\nRepeatedFieldBuilder` classes cache messages that were created so that messages only need to be\ncreated when some change occurred in its builder or a builder for one of its descendants. \n\nInheritance\n-----------\n\n[java.lang.Object](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html) \\\u003e SingleFieldBuilder\\\u003cMType,BType,IType\\\u003e \n\nImplements\n----------\n\n[GeneratedMessage.BuilderParent](/java/docs/reference/protobuf/latest/com.google.protobuf.GeneratedMessage.BuilderParent) \n\nInherited Members\n-----------------\n\n[Object.clone()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#clone--) \n[Object.equals(Object)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-) \n[Object.finalize()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#finalize--) \n[Object.getClass()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#getClass--) \n[Object.hashCode()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#hashCode--) \n[Object.notify()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notify--) \n[Object.notifyAll()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notifyAll--) \n[Object.toString()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--) \n[Object.wait()](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait--) \n[Object.wait(long)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-) \n[Object.wait(long,int)](https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-int-)\n\nConstructors\n------------\n\n### SingleFieldBuilder(MType message, GeneratedMessage.BuilderParent parent, boolean isClean)\n\n public SingleFieldBuilder(MType message, GeneratedMessage.BuilderParent parent, boolean isClean)\n\nMethods\n-------\n\n### build()\n\n public MType build()\n\nBuilds the message and returns it.\n\n### clear()\n\n public SingleFieldBuilder\u003cMType,BType,IType\u003e clear()\n\nClears the value of the field.\n\n### dispose()\n\n public void dispose()\n\n### getBuilder()\n\n public BType getBuilder()\n\nGets a builder for the field. If no builder has been created yet, a builder is created on\ndemand by calling [Message#toBuilder](/java/docs/reference/protobuf/latest/com.google.protobuf.Message#com_google_protobuf_Message_toBuilder_).\n\n### getMessage()\n\n public MType getMessage()\n\nGet the message for the field. If the message is currently stored as a `Builder`, it is\nconverted to a `Message` by calling [Message.Builder#buildPartial](/java/docs/reference/protobuf/latest/com.google.protobuf.Message.Builder#com_google_protobuf_Message_Builder_buildPartial_) on it. If no\nmessage has been set, returns the default instance of the message.\n\n### getMessageOrBuilder()\n\n public IType getMessageOrBuilder()\n\nGets the base class interface for the field. This may either be a builder or a message. It will\nreturn whatever is more efficient.\n\n### markDirty()\n\n public void markDirty()\n\nA builder becomes dirty whenever a field is modified -- including fields in nested builders\n-- and becomes clean when build() is called. Thus, when a builder becomes dirty, all its\nparents become dirty as well, and when it becomes clean, all its children become clean. The\ndirtiness state is used to invalidate certain cached values.\n\nTo this end, a builder calls markDirty() on its parent whenever it transitions from clean\nto dirty. The parent must propagate this call to its own parent, unless it was already dirty,\nin which case the grandparent must necessarily already be dirty as well. The parent can only\ntransition back to \"clean\" after calling build() on all children.\n\n### mergeFrom(MType value)\n\n public SingleFieldBuilder\u003cMType,BType,IType\u003e mergeFrom(MType value)\n\nMerges the field from another field.\n\n### setMessage(MType message)\n\n public SingleFieldBuilder\u003cMType,BType,IType\u003e setMessage(MType message)\n\nSets a message for the field replacing any existing value."]]
