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.io.IOException; 34 import java.util.List; 35 import java.util.Map; 36 37 /** A reader of fields from a serialized protobuf message. */ 38 // TODO(nathanmittler): Refactor to allow the reader to allocate properly sized lists. 39 @ExperimentalApi 40 interface Reader { 41 /** Value used to indicate that the end of input has been reached. */ 42 int READ_DONE = Integer.MAX_VALUE; 43 44 /** Value used to indicate that the reader does not know the tag about the field. */ 45 int TAG_UNKNOWN = 0; 46 shouldDiscardUnknownFields()47 boolean shouldDiscardUnknownFields(); 48 49 /** 50 * Gets the field number for the current field being read. 51 * 52 * <p>TODO(liujisi): Rename it to make it more explicit about the side effect on the underlying 53 * buffer. 54 * 55 * @return the current field number or {@link #READ_DONE} if the end of input has been reached. 56 */ getFieldNumber()57 int getFieldNumber() throws IOException; 58 59 /** 60 * Gets the wire tag of the current field. 61 * 62 * @return the current wire tag or {@link #TAG_UNKNOWN} if the reader does not know the tag of the 63 * current field. 64 */ getTag()65 int getTag(); 66 67 /** 68 * Skips the current field and advances the reader to the next field. 69 * 70 * @return {@code true} if there are more fields or {@code false} if the end of input has been 71 * reached. 72 */ skipField()73 boolean skipField() throws IOException; 74 75 /** 76 * Reads and returns the next field of type {@code DOUBLE} and advances the reader to the next 77 * field. 78 */ readDouble()79 double readDouble() throws IOException; 80 81 /** 82 * Reads and returns the next field of type {@code FLOAT} and advances the reader to the next 83 * field. 84 */ readFloat()85 float readFloat() throws IOException; 86 87 /** 88 * Reads and returns the next field of type {@code UINT64} and advances the reader to the next 89 * field. 90 */ readUInt64()91 long readUInt64() throws IOException; 92 93 /** 94 * Reads and returns the next field of type {@code INT64} and advances the reader to the next 95 * field. 96 */ readInt64()97 long readInt64() throws IOException; 98 99 /** 100 * Reads and returns the next field of type {@code INT32} and advances the reader to the next 101 * field. 102 */ readInt32()103 int readInt32() throws IOException; 104 105 /** 106 * Reads and returns the next field of type {@code FIXED64} and advances the reader to the next 107 * field. 108 */ readFixed64()109 long readFixed64() throws IOException; 110 111 /** 112 * Reads and returns the next field of type {@code FIXED32} and advances the reader to the next 113 * field. 114 */ readFixed32()115 int readFixed32() throws IOException; 116 117 /** 118 * Reads and returns the next field of type {@code BOOL} and advances the reader to the next 119 * field. 120 */ readBool()121 boolean readBool() throws IOException; 122 123 /** 124 * Reads and returns the next field of type {@code STRING} and advances the reader to the next 125 * field. If the stream contains malformed UTF-8, replace the offending bytes with the standard 126 * UTF-8 replacement character. 127 */ readString()128 String readString() throws IOException; 129 130 /** 131 * Reads and returns the next field of type {@code STRING} and advances the reader to the next 132 * field. If the stream contains malformed UTF-8, throw exception {@link 133 * InvalidProtocolBufferException}. 134 */ readStringRequireUtf8()135 String readStringRequireUtf8() throws IOException; 136 137 // TODO(yilunchong): the lack of other opinions for whether to expose this on the interface readMessageBySchemaWithCheck(Schema<T> schema, ExtensionRegistryLite extensionRegistry)138 <T> T readMessageBySchemaWithCheck(Schema<T> schema, ExtensionRegistryLite extensionRegistry) 139 throws IOException; 140 141 /** 142 * Reads and returns the next field of type {@code MESSAGE} and advances the reader to the next 143 * field. 144 */ readMessage(Class<T> clazz, ExtensionRegistryLite extensionRegistry)145 <T> T readMessage(Class<T> clazz, ExtensionRegistryLite extensionRegistry) throws IOException; 146 147 /** 148 * Reads and returns the next field of type {@code GROUP} and advances the reader to the next 149 * field. 150 * 151 * @deprecated groups fields are deprecated. 152 */ 153 @Deprecated readGroup(Class<T> clazz, ExtensionRegistryLite extensionRegistry)154 <T> T readGroup(Class<T> clazz, ExtensionRegistryLite extensionRegistry) throws IOException; 155 156 // TODO(yilunchong): the lack of other opinions for whether to expose this on the interface 157 @Deprecated readGroupBySchemaWithCheck(Schema<T> schema, ExtensionRegistryLite extensionRegistry)158 <T> T readGroupBySchemaWithCheck(Schema<T> schema, ExtensionRegistryLite extensionRegistry) 159 throws IOException; 160 161 /** 162 * Reads and returns the next field of type {@code BYTES} and advances the reader to the next 163 * field. 164 */ readBytes()165 ByteString readBytes() throws IOException; 166 167 /** 168 * Reads and returns the next field of type {@code UINT32} and advances the reader to the next 169 * field. 170 */ readUInt32()171 int readUInt32() throws IOException; 172 173 /** 174 * Reads and returns the next field of type {@code ENUM} and advances the reader to the next 175 * field. 176 */ readEnum()177 int readEnum() throws IOException; 178 179 /** 180 * Reads and returns the next field of type {@code SFIXED32} and advances the reader to the next 181 * field. 182 */ readSFixed32()183 int readSFixed32() throws IOException; 184 185 /** 186 * Reads and returns the next field of type {@code SFIXED64} and advances the reader to the next 187 * field. 188 */ readSFixed64()189 long readSFixed64() throws IOException; 190 191 /** 192 * Reads and returns the next field of type {@code SINT32} and advances the reader to the next 193 * field. 194 */ readSInt32()195 int readSInt32() throws IOException; 196 197 /** 198 * Reads and returns the next field of type {@code SINT64} and advances the reader to the next 199 * field. 200 */ readSInt64()201 long readSInt64() throws IOException; 202 203 /** 204 * Reads the next field of type {@code DOUBLE_LIST} or {@code DOUBLE_LIST_PACKED} and advances the 205 * reader to the next field. 206 * 207 * @param target the list that will receive the read values. 208 */ readDoubleList(List<Double> target)209 void readDoubleList(List<Double> target) throws IOException; 210 211 /** 212 * Reads the next field of type {@code FLOAT_LIST} or {@code FLOAT_LIST_PACKED} and advances the 213 * reader to the next field. 214 * 215 * @param target the list that will receive the read values. 216 */ readFloatList(List<Float> target)217 void readFloatList(List<Float> target) throws IOException; 218 219 /** 220 * Reads the next field of type {@code UINT64_LIST} or {@code UINT64_LIST_PACKED} and advances the 221 * reader to the next field. 222 * 223 * @param target the list that will receive the read values. 224 */ readUInt64List(List<Long> target)225 void readUInt64List(List<Long> target) throws IOException; 226 227 /** 228 * Reads the next field of type {@code INT64_LIST} or {@code INT64_LIST_PACKED} and advances the 229 * reader to the next field. 230 * 231 * @param target the list that will receive the read values. 232 */ readInt64List(List<Long> target)233 void readInt64List(List<Long> target) throws IOException; 234 235 /** 236 * Reads the next field of type {@code INT32_LIST} or {@code INT32_LIST_PACKED} and advances the 237 * reader to the next field. 238 * 239 * @param target the list that will receive the read values. 240 */ readInt32List(List<Integer> target)241 void readInt32List(List<Integer> target) throws IOException; 242 243 /** 244 * Reads the next field of type {@code FIXED64_LIST} or {@code FIXED64_LIST_PACKED} and advances 245 * the reader to the next field. 246 * 247 * @param target the list that will receive the read values. 248 */ readFixed64List(List<Long> target)249 void readFixed64List(List<Long> target) throws IOException; 250 251 /** 252 * Reads the next field of type {@code FIXED32_LIST} or {@code FIXED32_LIST_PACKED} and advances 253 * the reader to the next field. 254 * 255 * @param target the list that will receive the read values. 256 */ readFixed32List(List<Integer> target)257 void readFixed32List(List<Integer> target) throws IOException; 258 259 /** 260 * Reads the next field of type {@code BOOL_LIST} or {@code BOOL_LIST_PACKED} and advances the 261 * reader to the next field. 262 * 263 * @param target the list that will receive the read values. 264 */ readBoolList(List<Boolean> target)265 void readBoolList(List<Boolean> target) throws IOException; 266 267 /** 268 * Reads the next field of type {@code STRING_LIST} and advances the reader to the next field. 269 * 270 * @param target the list that will receive the read values. 271 */ readStringList(List<String> target)272 void readStringList(List<String> target) throws IOException; 273 274 /** 275 * Reads the next field of type {@code STRING_LIST} and advances the reader to the next field. If 276 * the stream contains malformed UTF-8, throw exception {@link InvalidProtocolBufferException}. 277 * 278 * @param target the list that will receive the read values. 279 */ readStringListRequireUtf8(List<String> target)280 void readStringListRequireUtf8(List<String> target) throws IOException; 281 282 /** 283 * Reads the next field of type {@code MESSAGE_LIST} and advances the reader to the next field. 284 * 285 * @param target the list that will receive the read values. 286 * @param targetType the type of the elements stored in the {@code target} list. 287 */ readMessageList( List<T> target, Schema<T> schema, ExtensionRegistryLite extensionRegistry)288 <T> void readMessageList( 289 List<T> target, Schema<T> schema, ExtensionRegistryLite extensionRegistry) throws IOException; 290 readMessageList( List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry)291 <T> void readMessageList( 292 List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry) 293 throws IOException; 294 295 /** 296 * Reads the next field of type {@code GROUP_LIST} and advances the reader to the next field. 297 * 298 * @param target the list that will receive the read values. 299 * @param targetType the type of the elements stored in the {@code target} list. 300 * @deprecated groups fields are deprecated. 301 */ 302 @Deprecated readGroupList( List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry)303 <T> void readGroupList( 304 List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry) 305 throws IOException; 306 307 @Deprecated readGroupList( List<T> target, Schema<T> targetType, ExtensionRegistryLite extensionRegistry)308 <T> void readGroupList( 309 List<T> target, Schema<T> targetType, ExtensionRegistryLite extensionRegistry) 310 throws IOException; 311 312 /** 313 * Reads the next field of type {@code BYTES_LIST} and advances the reader to the next field. 314 * 315 * @param target the list that will receive the read values. 316 */ readBytesList(List<ByteString> target)317 void readBytesList(List<ByteString> target) throws IOException; 318 319 /** 320 * Reads the next field of type {@code UINT32_LIST} or {@code UINT32_LIST_PACKED} and advances the 321 * reader to the next field. 322 * 323 * @param target the list that will receive the read values. 324 */ readUInt32List(List<Integer> target)325 void readUInt32List(List<Integer> target) throws IOException; 326 327 /** 328 * Reads the next field of type {@code ENUM_LIST} or {@code ENUM_LIST_PACKED} and advances the 329 * reader to the next field. 330 * 331 * @param target the list that will receive the read values. 332 */ readEnumList(List<Integer> target)333 void readEnumList(List<Integer> target) throws IOException; 334 335 /** 336 * Reads the next field of type {@code SFIXED32_LIST} or {@code SFIXED32_LIST_PACKED} and advances 337 * the reader to the next field. 338 * 339 * @param target the list that will receive the read values. 340 */ readSFixed32List(List<Integer> target)341 void readSFixed32List(List<Integer> target) throws IOException; 342 343 /** 344 * Reads the next field of type {@code SFIXED64_LIST} or {@code SFIXED64_LIST_PACKED} and advances 345 * the reader to the next field. 346 * 347 * @param target the list that will receive the read values. 348 */ readSFixed64List(List<Long> target)349 void readSFixed64List(List<Long> target) throws IOException; 350 351 /** 352 * Reads the next field of type {@code SINT32_LIST} or {@code SINT32_LIST_PACKED} and advances the 353 * reader to the next field. 354 * 355 * @param target the list that will receive the read values. 356 */ readSInt32List(List<Integer> target)357 void readSInt32List(List<Integer> target) throws IOException; 358 359 /** 360 * Reads the next field of type {@code SINT64_LIST} or {@code SINT64_LIST_PACKED} and advances the 361 * reader to the next field. 362 * 363 * @param target the list that will receive the read values. 364 */ readSInt64List(List<Long> target)365 void readSInt64List(List<Long> target) throws IOException; 366 367 /** 368 * Reads the next field of type {@code MAP} and advances the reader to the next field. 369 * 370 * @param target the mutable map that will receive the read values. 371 * @param mapDefaultEntry the default entry of the map field. 372 * @param extensionRegistry the extension registry for parsing message value fields. 373 */ readMap( Map<K, V> target, MapEntryLite.Metadata<K, V> mapDefaultEntry, ExtensionRegistryLite extensionRegistry)374 <K, V> void readMap( 375 Map<K, V> target, 376 MapEntryLite.Metadata<K, V> mapDefaultEntry, 377 ExtensionRegistryLite extensionRegistry) 378 throws IOException; 379 } 380