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 /** Read a message field from the wire format and merge the results into the given target. */ mergeMessageField(T target, Schema<T> schema, ExtensionRegistryLite extensionRegistry)162 <T> void mergeMessageField(T target, Schema<T> schema, ExtensionRegistryLite extensionRegistry) 163 throws IOException; 164 165 /** Read a group field from the wire format and merge the results into the given target. */ mergeGroupField(T target, Schema<T> schema, ExtensionRegistryLite extensionRegistry)166 <T> void mergeGroupField(T target, Schema<T> schema, ExtensionRegistryLite extensionRegistry) 167 throws IOException; 168 169 /** 170 * Reads and returns the next field of type {@code BYTES} and advances the reader to the next 171 * field. 172 */ readBytes()173 ByteString readBytes() throws IOException; 174 175 /** 176 * Reads and returns the next field of type {@code UINT32} and advances the reader to the next 177 * field. 178 */ readUInt32()179 int readUInt32() throws IOException; 180 181 /** 182 * Reads and returns the next field of type {@code ENUM} and advances the reader to the next 183 * field. 184 */ readEnum()185 int readEnum() throws IOException; 186 187 /** 188 * Reads and returns the next field of type {@code SFIXED32} and advances the reader to the next 189 * field. 190 */ readSFixed32()191 int readSFixed32() throws IOException; 192 193 /** 194 * Reads and returns the next field of type {@code SFIXED64} and advances the reader to the next 195 * field. 196 */ readSFixed64()197 long readSFixed64() throws IOException; 198 199 /** 200 * Reads and returns the next field of type {@code SINT32} and advances the reader to the next 201 * field. 202 */ readSInt32()203 int readSInt32() throws IOException; 204 205 /** 206 * Reads and returns the next field of type {@code SINT64} and advances the reader to the next 207 * field. 208 */ readSInt64()209 long readSInt64() throws IOException; 210 211 /** 212 * Reads the next field of type {@code DOUBLE_LIST} or {@code DOUBLE_LIST_PACKED} and advances the 213 * reader to the next field. 214 * 215 * @param target the list that will receive the read values. 216 */ readDoubleList(List<Double> target)217 void readDoubleList(List<Double> target) throws IOException; 218 219 /** 220 * Reads the next field of type {@code FLOAT_LIST} or {@code FLOAT_LIST_PACKED} and advances the 221 * reader to the next field. 222 * 223 * @param target the list that will receive the read values. 224 */ readFloatList(List<Float> target)225 void readFloatList(List<Float> target) throws IOException; 226 227 /** 228 * Reads the next field of type {@code UINT64_LIST} or {@code UINT64_LIST_PACKED} and advances the 229 * reader to the next field. 230 * 231 * @param target the list that will receive the read values. 232 */ readUInt64List(List<Long> target)233 void readUInt64List(List<Long> target) throws IOException; 234 235 /** 236 * Reads the next field of type {@code INT64_LIST} or {@code INT64_LIST_PACKED} and advances the 237 * reader to the next field. 238 * 239 * @param target the list that will receive the read values. 240 */ readInt64List(List<Long> target)241 void readInt64List(List<Long> target) throws IOException; 242 243 /** 244 * Reads the next field of type {@code INT32_LIST} or {@code INT32_LIST_PACKED} and advances the 245 * reader to the next field. 246 * 247 * @param target the list that will receive the read values. 248 */ readInt32List(List<Integer> target)249 void readInt32List(List<Integer> target) throws IOException; 250 251 /** 252 * Reads the next field of type {@code FIXED64_LIST} or {@code FIXED64_LIST_PACKED} and advances 253 * the reader to the next field. 254 * 255 * @param target the list that will receive the read values. 256 */ readFixed64List(List<Long> target)257 void readFixed64List(List<Long> target) throws IOException; 258 259 /** 260 * Reads the next field of type {@code FIXED32_LIST} or {@code FIXED32_LIST_PACKED} and advances 261 * the reader to the next field. 262 * 263 * @param target the list that will receive the read values. 264 */ readFixed32List(List<Integer> target)265 void readFixed32List(List<Integer> target) throws IOException; 266 267 /** 268 * Reads the next field of type {@code BOOL_LIST} or {@code BOOL_LIST_PACKED} and advances the 269 * reader to the next field. 270 * 271 * @param target the list that will receive the read values. 272 */ readBoolList(List<Boolean> target)273 void readBoolList(List<Boolean> target) throws IOException; 274 275 /** 276 * Reads the next field of type {@code STRING_LIST} and advances the reader to the next field. 277 * 278 * @param target the list that will receive the read values. 279 */ readStringList(List<String> target)280 void readStringList(List<String> target) throws IOException; 281 282 /** 283 * Reads the next field of type {@code STRING_LIST} and advances the reader to the next field. If 284 * the stream contains malformed UTF-8, throw exception {@link InvalidProtocolBufferException}. 285 * 286 * @param target the list that will receive the read values. 287 */ readStringListRequireUtf8(List<String> target)288 void readStringListRequireUtf8(List<String> target) throws IOException; 289 290 /** 291 * Reads the next field of type {@code MESSAGE_LIST} and advances the reader to the next field. 292 * 293 * @param target the list that will receive the read values. 294 * @param targetType the type of the elements stored in the {@code target} list. 295 */ readMessageList( List<T> target, Schema<T> schema, ExtensionRegistryLite extensionRegistry)296 <T> void readMessageList( 297 List<T> target, Schema<T> schema, ExtensionRegistryLite extensionRegistry) throws IOException; 298 readMessageList( List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry)299 <T> void readMessageList( 300 List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry) 301 throws IOException; 302 303 /** 304 * Reads the next field of type {@code GROUP_LIST} and advances the reader to the next field. 305 * 306 * @param target the list that will receive the read values. 307 * @param targetType the type of the elements stored in the {@code target} list. 308 * @deprecated groups fields are deprecated. 309 */ 310 @Deprecated readGroupList( List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry)311 <T> void readGroupList( 312 List<T> target, Class<T> targetType, ExtensionRegistryLite extensionRegistry) 313 throws IOException; 314 315 @Deprecated readGroupList( List<T> target, Schema<T> targetType, ExtensionRegistryLite extensionRegistry)316 <T> void readGroupList( 317 List<T> target, Schema<T> targetType, ExtensionRegistryLite extensionRegistry) 318 throws IOException; 319 320 /** 321 * Reads the next field of type {@code BYTES_LIST} and advances the reader to the next field. 322 * 323 * @param target the list that will receive the read values. 324 */ readBytesList(List<ByteString> target)325 void readBytesList(List<ByteString> target) throws IOException; 326 327 /** 328 * Reads the next field of type {@code UINT32_LIST} or {@code UINT32_LIST_PACKED} and advances the 329 * reader to the next field. 330 * 331 * @param target the list that will receive the read values. 332 */ readUInt32List(List<Integer> target)333 void readUInt32List(List<Integer> target) throws IOException; 334 335 /** 336 * Reads the next field of type {@code ENUM_LIST} or {@code ENUM_LIST_PACKED} and advances the 337 * reader to the next field. 338 * 339 * @param target the list that will receive the read values. 340 */ readEnumList(List<Integer> target)341 void readEnumList(List<Integer> target) throws IOException; 342 343 /** 344 * Reads the next field of type {@code SFIXED32_LIST} or {@code SFIXED32_LIST_PACKED} and advances 345 * the reader to the next field. 346 * 347 * @param target the list that will receive the read values. 348 */ readSFixed32List(List<Integer> target)349 void readSFixed32List(List<Integer> target) throws IOException; 350 351 /** 352 * Reads the next field of type {@code SFIXED64_LIST} or {@code SFIXED64_LIST_PACKED} and advances 353 * the reader to the next field. 354 * 355 * @param target the list that will receive the read values. 356 */ readSFixed64List(List<Long> target)357 void readSFixed64List(List<Long> target) throws IOException; 358 359 /** 360 * Reads the next field of type {@code SINT32_LIST} or {@code SINT32_LIST_PACKED} and advances the 361 * reader to the next field. 362 * 363 * @param target the list that will receive the read values. 364 */ readSInt32List(List<Integer> target)365 void readSInt32List(List<Integer> target) throws IOException; 366 367 /** 368 * Reads the next field of type {@code SINT64_LIST} or {@code SINT64_LIST_PACKED} and advances the 369 * reader to the next field. 370 * 371 * @param target the list that will receive the read values. 372 */ readSInt64List(List<Long> target)373 void readSInt64List(List<Long> target) throws IOException; 374 375 /** 376 * Reads the next field of type {@code MAP} and advances the reader to the next field. 377 * 378 * @param target the mutable map that will receive the read values. 379 * @param mapDefaultEntry the default entry of the map field. 380 * @param extensionRegistry the extension registry for parsing message value fields. 381 */ readMap( Map<K, V> target, MapEntryLite.Metadata<K, V> mapDefaultEntry, ExtensionRegistryLite extensionRegistry)382 <K, V> void readMap( 383 Map<K, V> target, 384 MapEntryLite.Metadata<K, V> mapDefaultEntry, 385 ExtensionRegistryLite extensionRegistry) 386 throws IOException; 387 } 388