RepeatedFieldBuilderV3
Date: 2017-07-08

com.google.protobuf

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

- java.lang.Object
- - com.google.protobuf.RepeatedFieldBuilderV3<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 RepeatedFieldBuilderV3<MType extends AbstractMessage,BType extends AbstractMessage.Builder,IType extends MessageOrBuilder>
      extends java.lang.Object
      implements AbstractMessage.BuilderParent

  `RepeatedFieldBuilderV3` implements a structure that a protocol message uses to hold a repeated field of other protocol messages. It supports the classical use case of adding immutable `Message`'s to the repeated field and is highly optimized around this (no extra memory allocations and sharing of immutable arrays).
  It also supports the additional use case of adding a `Message.Builder` to the repeated 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
    `RepeatedFieldBuilderV3(java.util.List<MType> messages, boolean isMessagesListMutable, AbstractMessage.BuilderParent parent, boolean isClean)` Constructs a new builder with an empty list of messages.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `RepeatedFieldBuilderV3<MType,BType,IType>` | `addAllMessages(java.lang.Iterable<? extends MType> values)` Appends all of the messages in the specified collection to the end of this list, in the order that they are returned by the specified collection's iterator.
    `BType` | `addBuilder(int index, MType message)` Inserts a new builder at the specified position in this list.
    `BType` | `addBuilder(MType message)` Appends a new builder to the end of this list and returns the builder.
    `RepeatedFieldBuilderV3<MType,BType,IType>` | `addMessage(int index, MType message)` Inserts the specified message at the specified position in this list.
    `RepeatedFieldBuilderV3<MType,BType,IType>` | `addMessage(MType message)` Appends the specified element to the end of this list.
    `java.util.List<MType>` | `build()` Builds the list of messages from the builder and returns them.
    `void` | `clear()` Removes all of the elements from this list.
    `void` | `dispose()`
    `BType` | `getBuilder(int index)` Gets a builder for the specified index.
    `java.util.List<BType>` | `getBuilderList()` Gets a view of the builder as a list of builders.
    `int` | `getCount()` Gets the count of items in the list.
    `MType` | `getMessage(int index)` Get the message at the specified index.
    `java.util.List<MType>` | `getMessageList()` Gets a view of the builder as a list of messages.
    `IType` | `getMessageOrBuilder(int index)` Gets the base class interface for the specified index.
    `java.util.List<IType>` | `getMessageOrBuilderList()` Gets a view of the builder as a list of MessageOrBuilders.
    `boolean` | `isEmpty()` Gets whether the list is empty.
    `void` | `markDirty()` A builder becomes dirty whenever a field is modified -- including fields in nested builders -- and becomes clean when build() is called.
    `void` | `remove(int index)` Removes the element at the specified position in this list.
    `RepeatedFieldBuilderV3<MType,BType,IType>` | `setMessage(int index, MType message)` Sets a message at the specified index replacing the existing item at that index.

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

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

- - ### Constructor Detail

    - #### RepeatedFieldBuilderV3

          public RepeatedFieldBuilderV3(java.util.List<MType> messages,
                                boolean isMessagesListMutable,
                                AbstractMessage.BuilderParent parent,
                                boolean isClean)

      Constructs a new builder with an empty list of messages.
      Parameters:
        `messages` - the current list of messages
        `isMessagesListMutable` - Whether the messages list is mutable
        `parent` - a listener to notify of changes
        `isClean` - whether the builder is initially marked clean

  - ### Method Detail

    - #### dispose

          public void dispose()

    - #### getCount

          public int getCount()

      Gets the count of items in the list.
      Returns:
        the count of items in the list.

    - #### isEmpty

          public boolean isEmpty()

      Gets whether the list is empty.
      Returns:
        whether the list is empty

    - #### getMessage

          public MType getMessage(int index)

      Get the message at the specified index. If the message is currently stored as a `Builder`, it is converted to a `Message` by calling `Message.Builder.buildPartial()` on it.
      Parameters:
        `index` - the index of the message to get
      Returns:
        the message for the specified index

    - #### getBuilder

          public BType getBuilder(int index)

      Gets a builder for the specified index. If no builder has been created for that index, a builder is created on demand by calling `Message.toBuilder()`.
      Parameters:
        `index` - the index of the message to get
      Returns:
        The builder for that index

    - #### getMessageOrBuilder

          public IType getMessageOrBuilder(int index)

      Gets the base class interface for the specified index. This may either be a builder or a message. It will return whatever is more efficient.
      Parameters:
        `index` - the index of the message to get
      Returns:
        the message or builder for the index as the base class interface

    - #### setMessage

          public RepeatedFieldBuilderV3<MType,BType,IType> setMessage(int index,
                                                             MType message)

      Sets a message at the specified index replacing the existing item at that index.
      Parameters:
        `index` - the index to set.
        `message` - the message to set
      Returns:
        the builder

    - #### addMessage

          public RepeatedFieldBuilderV3<MType,BType,IType> addMessage(MType message)

      Appends the specified element to the end of this list.
      Parameters:
        `message` - the message to add
      Returns:
        the builder

    - #### addMessage

          public RepeatedFieldBuilderV3<MType,BType,IType> addMessage(int index,
                                                             MType message)

      Inserts the specified message at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
      Parameters:
        `index` - the index at which to insert the message
        `message` - the message to add
      Returns:
        the builder

    - #### addAllMessages

          public RepeatedFieldBuilderV3<MType,BType,IType> addAllMessages(java.lang.Iterable<? extends MType> values)

      Appends all of the messages in the specified collection to the end of this list, in the order that they are returned by the specified collection's iterator.
      Parameters:
        `values` - the messages to add
      Returns:
        the builder

    - #### addBuilder

          public BType addBuilder(MType message)

      Appends a new builder to the end of this list and returns the builder.
      Parameters:
        `message` - the message to add which is the basis of the builder
      Returns:
        the new builder

    - #### addBuilder

          public BType addBuilder(int index,
                         MType message)

      Inserts a new builder at the specified position in this list. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
      Parameters:
        `index` - the index at which to insert the builder
        `message` - the message to add which is the basis of the builder
      Returns:
        the builder

    - #### remove

          public void remove(int index)

      Removes the element at the specified position in this list. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.
      Parameters:
        `index` - the index at which to remove the message

    - #### clear

          public void clear()

      Removes all of the elements from this list. The list will be empty after this call returns.

    - #### build

          public java.util.List<MType> build()

      Builds the list of messages from the builder and returns them.
      Returns:
        an immutable list of messages

    - #### getMessageList

          public java.util.List<MType> getMessageList()

      Gets a view of the builder as a list of messages. The returned list is live and will reflect any changes to the underlying builder.
      Returns:
        the messages in the list

    - #### getBuilderList

          public java.util.List<BType> getBuilderList()

      Gets a view of the builder as a list of builders. This returned list is live and will reflect any changes to the underlying builder.
      Returns:
        the builders in the list

    - #### getMessageOrBuilderList

          public java.util.List<IType> getMessageOrBuilderList()

      Gets a view of the builder as a list of MessageOrBuilders. This returned list is live and will reflect any changes to the underlying builder.
      Returns:
        the builders in the list

    - #### 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`