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