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