1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // https://developers.google.com/protocol-buffers/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 package com.google.protobuf; 32 33 import java.util.Collection; 34 import java.util.List; 35 36 /** 37 * An interface extending {@code List<String>} that also provides access to the items of the list as 38 * UTF8-encoded ByteString or byte[] objects. This is used by the protocol buffer implementation to 39 * support lazily converting bytes parsed over the wire to String objects until needed and also 40 * increases the efficiency of serialization if the String was never requested as the ByteString or 41 * byte[] is already cached. The ByteString methods are used in immutable API only and byte[] 42 * methods used in mutable API only for they use different representations for string/bytes fields. 43 * 44 * @author jonp@google.com (Jon Perlow) 45 */ 46 public interface LazyStringList extends ProtocolStringList { 47 48 /** 49 * Returns the element at the specified position in this list as a ByteString. 50 * 51 * @param index index of the element to return 52 * @return the element at the specified position in this list 53 * @throws IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= 54 * size()}) 55 */ getByteString(int index)56 ByteString getByteString(int index); 57 58 /** 59 * Returns the element at the specified position in this list as an Object that will either be a 60 * String or a ByteString. 61 * 62 * @param index index of the element to return 63 * @return the element at the specified position in this list 64 * @throws IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= 65 * size()}) 66 */ getRaw(int index)67 Object getRaw(int index); 68 69 /** 70 * Returns the element at the specified position in this list as byte[]. 71 * 72 * @param index index of the element to return 73 * @return the element at the specified position in this list 74 * @throws IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= 75 * size()}) 76 */ getByteArray(int index)77 byte[] getByteArray(int index); 78 79 /** 80 * Appends the specified element to the end of this list (optional operation). 81 * 82 * @param element element to be appended to this list 83 * @throws UnsupportedOperationException if the <tt>add</tt> operation is not supported by this 84 * list 85 */ add(ByteString element)86 void add(ByteString element); 87 88 /** 89 * Appends the specified element to the end of this list (optional operation). 90 * 91 * @param element element to be appended to this list 92 * @throws UnsupportedOperationException if the <tt>add</tt> operation is not supported by this 93 * list 94 */ add(byte[] element)95 void add(byte[] element); 96 97 /** 98 * Replaces the element at the specified position in this list with the specified element 99 * (optional operation). 100 * 101 * @param index index of the element to replace 102 * @param element the element to be stored at the specified position 103 * @throws UnsupportedOperationException if the <tt>set</tt> operation is not supported by this 104 * list IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= 105 * size()}) 106 */ set(int index, ByteString element)107 void set(int index, ByteString element); 108 109 /** 110 * Replaces the element at the specified position in this list with the specified element 111 * (optional operation). 112 * 113 * @param index index of the element to replace 114 * @param element the element to be stored at the specified position 115 * @throws UnsupportedOperationException if the <tt>set</tt> operation is not supported by this 116 * list IndexOutOfBoundsException if the index is out of range ({@code index < 0 || index >= 117 * size()}) 118 */ set(int index, byte[] element)119 void set(int index, byte[] element); 120 121 /** 122 * Appends all elements in the specified ByteString collection to the end of this list. 123 * 124 * @param c collection whose elements are to be added to this list 125 * @return true if this list changed as a result of the call 126 * @throws UnsupportedOperationException if the <tt>addAllByteString</tt> operation is not 127 * supported by this list 128 */ addAllByteString(Collection<? extends ByteString> c)129 boolean addAllByteString(Collection<? extends ByteString> c); 130 131 /** 132 * Appends all elements in the specified byte[] collection to the end of this list. 133 * 134 * @param c collection whose elements are to be added to this list 135 * @return true if this list changed as a result of the call 136 * @throws UnsupportedOperationException if the <tt>addAllByteArray</tt> operation is not 137 * supported by this list 138 */ addAllByteArray(Collection<byte[]> c)139 boolean addAllByteArray(Collection<byte[]> c); 140 141 /** 142 * Returns an unmodifiable List of the underlying elements, each of which is either a {@code 143 * String} or its equivalent UTF-8 encoded {@code ByteString} or byte[]. It is an error for the 144 * caller to modify the returned List, and attempting to do so will result in an {@link 145 * UnsupportedOperationException}. 146 */ getUnderlyingElements()147 List<?> getUnderlyingElements(); 148 149 /** 150 * Merges all elements from another LazyStringList into this one. This method differs from {@link 151 * #addAll(Collection)} on that underlying byte arrays are copied instead of reference shared. 152 * Immutable API doesn't need to use this method as byte[] is not used there at all. 153 */ mergeFrom(LazyStringList other)154 void mergeFrom(LazyStringList other); 155 156 /** 157 * Returns a mutable view of this list. Changes to the view will be made into the original list. 158 * This method is used in mutable API only. 159 */ asByteArrayList()160 List<byte[]> asByteArrayList(); 161 162 /** Returns an unmodifiable view of the list. */ getUnmodifiableView()163 LazyStringList getUnmodifiableView(); 164 } 165