LazyStringArrayList
Date: 2017-07-08

com.google.protobuf

## Class LazyStringArrayList

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractList<E>
    - - com.google.protobuf.LazyStringArrayList

- All Implemented Interfaces:
    Internal.ProtobufList<java.lang.String>, LazyStringList, ProtocolStringList, java.lang.Iterable<java.lang.String>, java.util.Collection<java.lang.String>, java.util.List<java.lang.String>, java.util.RandomAccess

      public class LazyStringArrayList
      extends java.util.AbstractList<E>
      implements LazyStringList, java.util.RandomAccess

  An implementation of `LazyStringList` that wraps an ArrayList. Each element is one of String, ByteString, or byte[]. It caches the last one requested which is most likely the one needed next. This minimizes memory usage while satisfying the most common use cases.

  Note that this implementation is not synchronized. If multiple threads access an `ArrayList` instance concurrently, and at least one of the threads modifies the list structurally, it must be synchronized externally. (A structural modification is any operation that adds or deletes one or more elements, or explicitly resizes the backing array; merely setting the value of an element is not a structural modification.) This is typically accomplished by synchronizing on some object that naturally encapsulates the list.

  If the implementation is accessed via concurrent reads, this is thread safe. Conversions are done in a thread safe manner. It's possible that the conversion may happen more than once if two threads attempt to access the same element and the modifications were not visible to each other, but this will not result in any corruption of the list or change in behavior other than performance.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static int` | `DEFAULT_CAPACITY`
    `static LazyStringList` | `EMPTY`

    - ### Fields inherited from class java.util.AbstractList

      `modCount`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LazyStringArrayList()`
    `LazyStringArrayList(int intialCapacity)`
    `LazyStringArrayList(LazyStringList from)`
    `LazyStringArrayList(java.util.List<java.lang.String> from)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(byte[] element)` Appends the specified element to the end of this list (optional operation).
    `void` | `add(ByteString element)` Appends the specified element to the end of this list (optional operation).
    `boolean` | `add(E e)`
    `void` | `add(int index, java.lang.String element)`
    `boolean` | `addAll(java.util.Collection<? extends java.lang.String> c)`
    `boolean` | `addAll(int index, java.util.Collection<? extends java.lang.String> c)`
    `boolean` | `addAllByteArray(java.util.Collection<byte[]> c)` Appends all elements in the specified byte[] collection to the end of this list.
    `boolean` | `addAllByteString(java.util.Collection<? extends ByteString> values)` Appends all elements in the specified ByteString collection to the end of this list.
    `java.util.List<byte[]>` | `asByteArrayList()` Returns a mutable view of this list.
    `java.util.List<ByteString>` | `asByteStringList()` Returns a view of the data as a list of ByteStrings.
    `void` | `clear()`
    `protected void` | `ensureIsMutable()` Throws an `UnsupportedOperationException` if the list is immutable.
    `boolean` | `equals(java.lang.Object o)`
    `java.lang.String` | `get(int index)`
    `byte[]` | `getByteArray(int index)` Returns the element at the specified position in this list as byte[].
    `ByteString` | `getByteString(int index)` Returns the element at the specified position in this list as a ByteString.
    `java.lang.Object` | `getRaw(int index)` Returns the element at the specified position in this list as an Object that will either be a String or a ByteString.
    `java.util.List<?>` | `getUnderlyingElements()` Returns an unmodifiable List of the underlying elements, each of which is either a `String` or its equivalent UTF-8 encoded `ByteString` or byte[].
    `LazyStringList` | `getUnmodifiableView()` Returns an unmodifiable view of the list.
    `int` | `hashCode()`
    `boolean` | `isModifiable()` Returns whether this list can be modified via the publicly accessible `List` methods.
    `void` | `makeImmutable()` Makes this list immutable.
    `void` | `mergeFrom(LazyStringList other)` Merges all elements from another LazyStringList into this one.
    `LazyStringArrayList` | `mutableCopyWithCapacity(int capacity)` Returns a mutable clone of this list with the specified capacity.
    `java.lang.String` | `remove(int index)`
    `boolean` | `remove(java.lang.Object o)`
    `boolean` | `removeAll(java.util.Collection<?> c)`
    `boolean` | `retainAll(java.util.Collection<?> c)`
    `void` | `set(int index, byte[] s)` Replaces the element at the specified position in this list with the specified element (optional operation).
    `void` | `set(int index, ByteString s)` Replaces the element at the specified position in this list with the specified element (optional operation).
    `java.lang.String` | `set(int index, java.lang.String s)`
    `int` | `size()`

    - ### Methods inherited from class java.util.AbstractList

      `indexOf, iterator, lastIndexOf, listIterator, listIterator, removeRange, subList`

    - ### Methods inherited from class java.util.AbstractCollection

      `contains, containsAll, isEmpty, toArray, toArray, toString`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.List

      `add, contains, containsAll, equals, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, removeAll, retainAll, subList, toArray, toArray`

- - ### Field Detail

    - #### EMPTY

          public static final LazyStringList EMPTY

    - #### DEFAULT_CAPACITY

          protected static final int DEFAULT_CAPACITY

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### LazyStringArrayList

          public LazyStringArrayList()

    - #### LazyStringArrayList

          public LazyStringArrayList(int intialCapacity)

    - #### LazyStringArrayList

          public LazyStringArrayList(LazyStringList from)

    - #### LazyStringArrayList

          public LazyStringArrayList(java.util.List<java.lang.String> from)

  - ### Method Detail

    - #### mutableCopyWithCapacity

          public LazyStringArrayList mutableCopyWithCapacity(int capacity)

      Description copied from interface: `Internal.ProtobufList`
      Returns a mutable clone of this list with the specified capacity.
      Specified by:
        `mutableCopyWithCapacity` in interface `Internal.ProtobufList<java.lang.String>`

    - #### get

          public java.lang.String get(int index)

      Specified by:
        `get` in interface `java.util.List<java.lang.String>`
      Specified by:
        `get` in class `java.util.AbstractList<java.lang.String>`

    - #### size

          public int size()

      Specified by:
        `size` in interface `java.util.Collection<java.lang.String>`
      Specified by:
        `size` in interface `java.util.List<java.lang.String>`
      Specified by:
        `size` in class `java.util.AbstractCollection<java.lang.String>`

    - #### set

          public java.lang.String set(int index,
                             java.lang.String s)

      Specified by:
        `set` in interface `java.util.List<java.lang.String>`

    - #### add

          public void add(int index,
                 java.lang.String element)

      Specified by:
        `add` in interface `java.util.List<java.lang.String>`

    - #### addAll

          public boolean addAll(java.util.Collection<? extends java.lang.String> c)

      Specified by:
        `addAll` in interface `java.util.Collection<java.lang.String>`
      Specified by:
        `addAll` in interface `java.util.List<java.lang.String>`

    - #### addAll

          public boolean addAll(int index,
                       java.util.Collection<? extends java.lang.String> c)

      Specified by:
        `addAll` in interface `java.util.List<java.lang.String>`

    - #### addAllByteString

          public boolean addAllByteString(java.util.Collection<? extends ByteString> values)

      Description copied from interface: `LazyStringList`
      Appends all elements in the specified ByteString collection to the end of this list.
      Specified by:
        `addAllByteString` in interface `LazyStringList`
      Parameters:
        `values` - collection whose elements are to be added to this list
      Returns:
        true if this list changed as a result of the call

    - #### addAllByteArray

          public boolean addAllByteArray(java.util.Collection<byte[]> c)

      Description copied from interface: `LazyStringList`
      Appends all elements in the specified byte[] collection to the end of this list.
      Specified by:
        `addAllByteArray` in interface `LazyStringList`
      Parameters:
        `c` - collection whose elements are to be added to this list
      Returns:
        true if this list changed as a result of the call

    - #### remove

          public java.lang.String remove(int index)

      Specified by:
        `remove` in interface `java.util.List<java.lang.String>`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `java.util.Collection<java.lang.String>`
      Specified by:
        `clear` in interface `java.util.List<java.lang.String>`

    - #### add

          public void add(ByteString element)

      Description copied from interface: `LazyStringList`
      Appends the specified element to the end of this list (optional operation).
      Specified by:
        `add` in interface `LazyStringList`
      Parameters:
        `element` - element to be appended to this list

    - #### add

          public void add(byte[] element)

      Description copied from interface: `LazyStringList`
      Appends the specified element to the end of this list (optional operation).
      Specified by:
        `add` in interface `LazyStringList`
      Parameters:
        `element` - element to be appended to this list

    - #### getRaw

          public java.lang.Object getRaw(int index)

      Description copied from interface: `LazyStringList`
      Returns the element at the specified position in this list as an Object that will either be a String or a ByteString.
      Specified by:
        `getRaw` in interface `LazyStringList`
      Parameters:
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list

    - #### getByteString

          public ByteString getByteString(int index)

      Description copied from interface: `LazyStringList`
      Returns the element at the specified position in this list as a ByteString.
      Specified by:
        `getByteString` in interface `LazyStringList`
      Parameters:
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list

    - #### getByteArray

          public byte[] getByteArray(int index)

      Description copied from interface: `LazyStringList`
      Returns the element at the specified position in this list as byte[].
      Specified by:
        `getByteArray` in interface `LazyStringList`
      Parameters:
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list

    - #### set

          public void set(int index,
                 ByteString s)

      Description copied from interface: `LazyStringList`
      Replaces the element at the specified position in this list with the specified element (optional operation).
      Specified by:
        `set` in interface `LazyStringList`
      Parameters:
        `index` - index of the element to replace
        `s` - the element to be stored at the specified position

    - #### set

          public void set(int index,
                 byte[] s)

      Description copied from interface: `LazyStringList`
      Replaces the element at the specified position in this list with the specified element (optional operation).
      Specified by:
        `set` in interface `LazyStringList`
      Parameters:
        `index` - index of the element to replace
        `s` - the element to be stored at the specified position

    - #### getUnderlyingElements

          public java.util.List<?> getUnderlyingElements()

      Description copied from interface: `LazyStringList`
      Returns an unmodifiable List of the underlying elements, each of which is either a `String` or its equivalent UTF-8 encoded `ByteString` or byte[]. It is an error for the caller to modify the returned List, and attempting to do so will result in an `UnsupportedOperationException`.
      Specified by:
        `getUnderlyingElements` in interface `LazyStringList`

    - #### mergeFrom

          public void mergeFrom(LazyStringList other)

      Description copied from interface: `LazyStringList`
      Merges all elements from another LazyStringList into this one. This method differs from `List.addAll(Collection)` on that underlying byte arrays are copied instead of reference shared. Immutable API doesn't need to use this method as byte[] is not used there at all.
      Specified by:
        `mergeFrom` in interface `LazyStringList`

    - #### asByteArrayList

          public java.util.List<byte[]> asByteArrayList()

      Description copied from interface: `LazyStringList`
      Returns a mutable view of this list. Changes to the view will be made into the original list. This method is used in mutable API only.
      Specified by:
        `asByteArrayList` in interface `LazyStringList`

    - #### asByteStringList

          public java.util.List<ByteString> asByteStringList()

      Description copied from interface: `ProtocolStringList`
      Returns a view of the data as a list of ByteStrings.
      Specified by:
        `asByteStringList` in interface `ProtocolStringList`

    - #### getUnmodifiableView

          public LazyStringList getUnmodifiableView()

      Description copied from interface: `LazyStringList`
      Returns an unmodifiable view of the list.
      Specified by:
        `getUnmodifiableView` in interface `LazyStringList`

    - #### equals

          public boolean equals(java.lang.Object o)

      Specified by:
        `equals` in interface `java.util.Collection<E>`
      Specified by:
        `equals` in interface `java.util.List<E>`
      Overrides:
        `equals` in class `java.util.AbstractList<E>`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `java.util.Collection<E>`
      Specified by:
        `hashCode` in interface `java.util.List<E>`
      Overrides:
        `hashCode` in class `java.util.AbstractList<E>`

    - #### add

          public boolean add(E e)

      Specified by:
        `add` in interface `java.util.Collection<E>`
      Specified by:
        `add` in interface `java.util.List<E>`
      Overrides:
        `add` in class `java.util.AbstractList<E>`

    - #### isModifiable

          public boolean isModifiable()

      Description copied from interface: `Internal.ProtobufList`
      Returns whether this list can be modified via the publicly accessible `List` methods.
      Specified by:
        `isModifiable` in interface `Internal.ProtobufList<E>`

    - #### makeImmutable

          public final void makeImmutable()

      Description copied from interface: `Internal.ProtobufList`
      Makes this list immutable. All subsequent modifications will throw an `UnsupportedOperationException`.
      Specified by:
        `makeImmutable` in interface `Internal.ProtobufList<E>`

    - #### remove

          public boolean remove(java.lang.Object o)

      Specified by:
        `remove` in interface `java.util.Collection<E>`
      Specified by:
        `remove` in interface `java.util.List<E>`
      Overrides:
        `remove` in class `java.util.AbstractCollection<E>`

    - #### removeAll

          public boolean removeAll(java.util.Collection<?> c)

      Specified by:
        `removeAll` in interface `java.util.Collection<E>`
      Specified by:
        `removeAll` in interface `java.util.List<E>`
      Overrides:
        `removeAll` in class `java.util.AbstractCollection<E>`

    - #### retainAll

          public boolean retainAll(java.util.Collection<?> c)

      Specified by:
        `retainAll` in interface `java.util.Collection<E>`
      Specified by:
        `retainAll` in interface `java.util.List<E>`
      Overrides:
        `retainAll` in class `java.util.AbstractCollection<E>`

    - #### ensureIsMutable

          protected void ensureIsMutable()

      Throws an `UnsupportedOperationException` if the list is immutable. Subclasses are responsible for invoking this method on mutate operations.