| // Protocol Buffers - Google's data interchange format |
| // Copyright 2008 Google Inc. All rights reserved. |
| // https://developers.google.com/protocol-buffers/ |
| // |
| // Redistribution and use in source and binary forms, with or without |
| // modification, are permitted provided that the following conditions are |
| // met: |
| // |
| // * Redistributions of source code must retain the above copyright |
| // notice, this list of conditions and the following disclaimer. |
| // * Redistributions in binary form must reproduce the above |
| // copyright notice, this list of conditions and the following disclaimer |
| // in the documentation and/or other materials provided with the |
| // distribution. |
| // * Neither the name of Google Inc. nor the names of its |
| // contributors may be used to endorse or promote products derived from |
| // this software without specific prior written permission. |
| // |
| // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| |
| package com.google.protobuf; |
| |
| import java.util.Collection; |
| import java.util.List; |
| |
| /** |
| * An interface extending {@code List<String>} that also provides access to the items of the list as |
| * UTF8-encoded ByteString or byte[] objects. This is used by the protocol buffer implementation to |
| * support lazily converting bytes parsed over the wire to String objects until needed and also |
| * increases the efficiency of serialization if the String was never requested as the ByteString or |
| * byte[] is already cached. The ByteString methods are used in immutable API only and byte[] |
| * methods used in mutable API only for they use different representations for string/bytes fields. |
| * |
| * @author jonp@google.com (Jon Perlow) |
| */ |
| public interface LazyStringList extends ProtocolStringList { |
| |
| /** |
| * Returns the element at the specified position in this list as a ByteString. |
| * |
| * @param index index of the element to return |
| * @return the element at the specified position in this list |
| * @throws IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= |
| * size()}) |
| */ |
| ByteString getByteString(int index); |
| |
| /** |
| * Returns the element at the specified position in this list as an Object that will either be a |
| * String or a ByteString. |
| * |
| * @param index index of the element to return |
| * @return the element at the specified position in this list |
| * @throws IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= |
| * size()}) |
| */ |
| Object getRaw(int index); |
| |
| /** |
| * Returns the element at the specified position in this list as byte[]. |
| * |
| * @param index index of the element to return |
| * @return the element at the specified position in this list |
| * @throws IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= |
| * size()}) |
| */ |
| byte[] getByteArray(int index); |
| |
| /** |
| * Appends the specified element to the end of this list (optional operation). |
| * |
| * @param element element to be appended to this list |
| * @throws UnsupportedOperationException if the <tt>add</tt> operation is not supported by this |
| * list |
| */ |
| void add(ByteString element); |
| |
| /** |
| * Appends the specified element to the end of this list (optional operation). |
| * |
| * @param element element to be appended to this list |
| * @throws UnsupportedOperationException if the <tt>add</tt> operation is not supported by this |
| * list |
| */ |
| void add(byte[] element); |
| |
| /** |
| * Replaces the element at the specified position in this list with the specified element |
| * (optional operation). |
| * |
| * @param index index of the element to replace |
| * @param element the element to be stored at the specified position |
| * @throws UnsupportedOperationException if the <tt>set</tt> operation is not supported by this |
| * list IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= |
| * size()}) |
| */ |
| void set(int index, ByteString element); |
| |
| /** |
| * Replaces the element at the specified position in this list with the specified element |
| * (optional operation). |
| * |
| * @param index index of the element to replace |
| * @param element the element to be stored at the specified position |
| * @throws UnsupportedOperationException if the <tt>set</tt> operation is not supported by this |
| * list IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= |
| * size()}) |
| */ |
| void set(int index, byte[] element); |
| |
| /** |
| * Appends all elements in the specified ByteString collection to the end of this list. |
| * |
| * @param c collection whose elements are to be added to this list |
| * @return true if this list changed as a result of the call |
| * @throws UnsupportedOperationException if the <tt>addAllByteString</tt> operation is not |
| * supported by this list |
| */ |
| boolean addAllByteString(Collection<? extends ByteString> c); |
| |
| /** |
| * Appends all elements in the specified byte[] collection to the end of this list. |
| * |
| * @param c collection whose elements are to be added to this list |
| * @return true if this list changed as a result of the call |
| * @throws UnsupportedOperationException if the <tt>addAllByteArray</tt> operation is not |
| * supported by this list |
| */ |
| boolean addAllByteArray(Collection<byte[]> c); |
| |
| /** |
| * Returns an unmodifiable List of the underlying elements, each of which is either a {@code |
| * String} or its equivalent UTF-8 encoded {@code ByteString} or byte[]. It is an error for the |
| * caller to modify the returned List, and attempting to do so will result in an {@link |
| * UnsupportedOperationException}. |
| */ |
| List<?> getUnderlyingElements(); |
| |
| /** |
| * Merges all elements from another LazyStringList into this one. This method differs from {@link |
| * #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. |
| */ |
| void mergeFrom(LazyStringList other); |
| |
| /** |
| * 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. |
| */ |
| List<byte[]> asByteArrayList(); |
| |
| /** Returns an unmodifiable view of the list. */ |
| LazyStringList getUnmodifiableView(); |
| } |