SingleFieldBuilderV3
Date: 2017-07-08

com.google.protobuf

## Class SingleFieldBuilderV3<MType extends AbstractMessage,BType extends AbstractMessage.Builder,IType extends MessageOrBuilder>

- java.lang.Object
- - com.google.protobuf.SingleFieldBuilderV3<MType,BType,IType>

- Type Parameters:
    `MType` - the type of message for the field
    `BType` - the type of builder for the field
    `IType` - the common interface for the message and the builder
  All Implemented Interfaces:
    AbstractMessage.BuilderParent

      public class SingleFieldBuilderV3<MType extends AbstractMessage,BType extends AbstractMessage.Builder,IType extends MessageOrBuilder>
      extends java.lang.Object
      implements AbstractMessage.BuilderParent

  `SingleFieldBuilderV3` implements 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 immutable `Message` as the value of the field and is highly optimized around this.
  It also supports the additional use case of setting a `Message.Builder` as the field and deferring conversion of that `Builder` to an immutable `Message`. In this way, it's possible to maintain a tree of `Builder`'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, the `SingleFieldBuilderV3` and `RepeatedFieldBuilderV3` classes 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.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SingleFieldBuilderV3(MType message, AbstractMessage.BuilderParent parent, boolean isClean)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `MType` | `build()` Builds the message and returns it.
    `SingleFieldBuilderV3<MType,BType,IType>` | `clear()` Clears the value of the field.
    `void` | `dispose()`
    `BType` | `getBuilder()` Gets a builder for the field.
    `MType` | `getMessage()` Get the message for the field.
    `IType` | `getMessageOrBuilder()` Gets the base class interface for the field.
    `void` | `markDirty()` A builder becomes dirty whenever a field is modified -- including fields in nested builders -- and becomes clean when build() is called.
    `SingleFieldBuilderV3<MType,BType,IType>` | `mergeFrom(MType value)` Merges the field from another field.
    `SingleFieldBuilderV3<MType,BType,IType>` | `setMessage(MType message)` Sets a message for the field replacing any existing value.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SingleFieldBuilderV3

          public SingleFieldBuilderV3(MType message,
                              AbstractMessage.BuilderParent parent,
                              boolean isClean)

  - ### Method Detail

    - #### dispose

          public void dispose()

    - #### getMessage

          public MType getMessage()

      Get the message for the field. If the message is currently stored as a `Builder`, it is converted to a `Message` by calling `Message.Builder.buildPartial()` on it. If no message has been set, returns the default instance of the message.
      Returns:
        the message for the field

    - #### build

          public MType build()

      Builds the message and returns it.
      Returns:
        the message

    - #### getBuilder

          public BType getBuilder()

      Gets a builder for the field. If no builder has been created yet, a builder is created on demand by calling `Message.toBuilder()`.
      Returns:
        The builder for the field

    - #### getMessageOrBuilder

          public IType getMessageOrBuilder()

      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:
        the message or builder for the field as the base class interface

    - #### setMessage

          public SingleFieldBuilderV3<MType,BType,IType> setMessage(MType message)

      Sets a message for the field replacing any existing value.
      Parameters:
        `message` - the message to set
      Returns:
        the builder

    - #### mergeFrom

          public SingleFieldBuilderV3<MType,BType,IType> mergeFrom(MType value)

      Merges the field from another field.
      Parameters:
        `value` - the value to merge from
      Returns:
        the builder

    - #### clear

          public SingleFieldBuilderV3<MType,BType,IType> clear()

      Clears the value of the field.
      Returns:
        the builder

    - #### markDirty

          public void markDirty()

      Description copied from interface: `AbstractMessage.BuilderParent`
      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.
      Specified by:
        `markDirty` in interface `AbstractMessage.BuilderParent`