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.InputStream; 11 import java.nio.ByteBuffer; 12 13 /** 14 * Abstract interface for parsing Protocol Messages. 15 * 16 * <p>The implementation should be stateless and thread-safe. 17 * 18 * <p>All methods may throw {@link InvalidProtocolBufferException}. In the event of invalid data, 19 * like an encoding error, the cause of the thrown exception will be {@code null}. However, if an 20 * I/O problem occurs, an exception is thrown with an {@link java.io.IOException} cause. 21 * 22 * @author liujisi@google.com (Pherl Liu) 23 */ 24 public interface Parser<MessageType> { 25 26 // NB(jh): Other parts of the protobuf API that parse messages distinguish between an I/O problem 27 // (like failure reading bytes from a socket) and invalid data (encoding error) via the type of 28 // thrown exception. But it would be source-incompatible to make the methods in this interface do 29 // so since they were originally spec'ed to only throw InvalidProtocolBufferException. So callers 30 // must inspect the cause of the exception to distinguish these two cases. 31 32 /** 33 * Parses a message of {@code MessageType} from the input. 34 * 35 * <p>Note: The caller should call {@link CodedInputStream#checkLastTagWas(int)} after calling 36 * this to verify that the last tag seen was the appropriate end-group tag, or zero for EOF. 37 */ parseFrom(CodedInputStream input)38 public MessageType parseFrom(CodedInputStream input) throws InvalidProtocolBufferException; 39 40 /** 41 * Like {@link #parseFrom(CodedInputStream)}, but also parses extensions. The extensions that you 42 * want to be able to parse must be registered in {@code extensionRegistry}. Extensions not in the 43 * registry will be treated as unknown fields. 44 */ parseFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry)45 public MessageType parseFrom(CodedInputStream input, ExtensionRegistryLite extensionRegistry) 46 throws InvalidProtocolBufferException; 47 48 /** 49 * Like {@link #parseFrom(CodedInputStream)}, but does not throw an exception if the message is 50 * missing required fields. Instead, a partial message is returned. 51 */ parsePartialFrom(CodedInputStream input)52 public MessageType parsePartialFrom(CodedInputStream input) throws InvalidProtocolBufferException; 53 54 /** 55 * Like {@link #parseFrom(CodedInputStream input, ExtensionRegistryLite)}, but does not throw an 56 * exception if the message is missing required fields. Instead, a partial message is returned. 57 */ parsePartialFrom( CodedInputStream input, ExtensionRegistryLite extensionRegistry)58 public MessageType parsePartialFrom( 59 CodedInputStream input, ExtensionRegistryLite extensionRegistry) 60 throws InvalidProtocolBufferException; 61 62 // --------------------------------------------------------------- 63 // Convenience methods. 64 65 /** 66 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 67 * {@link #parseFrom(CodedInputStream)}. 68 */ parseFrom(ByteBuffer data)69 public MessageType parseFrom(ByteBuffer data) throws InvalidProtocolBufferException; 70 71 /** 72 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 73 * {@link #parseFrom(CodedInputStream, ExtensionRegistryLite)}. 74 */ parseFrom(ByteBuffer data, ExtensionRegistryLite extensionRegistry)75 public MessageType parseFrom(ByteBuffer data, ExtensionRegistryLite extensionRegistry) 76 throws InvalidProtocolBufferException; 77 /** 78 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 79 * {@link #parseFrom(CodedInputStream)}. 80 */ parseFrom(ByteString data)81 public MessageType parseFrom(ByteString data) throws InvalidProtocolBufferException; 82 83 /** 84 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 85 * {@link #parseFrom(CodedInputStream, ExtensionRegistryLite)}. 86 */ parseFrom(ByteString data, ExtensionRegistryLite extensionRegistry)87 public MessageType parseFrom(ByteString data, ExtensionRegistryLite extensionRegistry) 88 throws InvalidProtocolBufferException; 89 90 /** 91 * Like {@link #parseFrom(ByteString)}, but does not throw an exception if the message is missing 92 * required fields. Instead, a partial message is returned. 93 */ parsePartialFrom(ByteString data)94 public MessageType parsePartialFrom(ByteString data) throws InvalidProtocolBufferException; 95 96 /** 97 * Like {@link #parseFrom(ByteString, ExtensionRegistryLite)}, but does not throw an exception if 98 * the message is missing required fields. Instead, a partial message is returned. 99 */ parsePartialFrom(ByteString data, ExtensionRegistryLite extensionRegistry)100 public MessageType parsePartialFrom(ByteString data, ExtensionRegistryLite extensionRegistry) 101 throws InvalidProtocolBufferException; 102 103 /** 104 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 105 * {@link #parseFrom(CodedInputStream)}. 106 */ parseFrom(byte[] data, int off, int len)107 public MessageType parseFrom(byte[] data, int off, int len) throws InvalidProtocolBufferException; 108 109 /** 110 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 111 * {@link #parseFrom(CodedInputStream, ExtensionRegistryLite)}. 112 */ parseFrom( byte[] data, int off, int len, ExtensionRegistryLite extensionRegistry)113 public MessageType parseFrom( 114 byte[] data, int off, int len, ExtensionRegistryLite extensionRegistry) 115 throws InvalidProtocolBufferException; 116 117 /** 118 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 119 * {@link #parseFrom(CodedInputStream)}. 120 */ parseFrom(byte[] data)121 public MessageType parseFrom(byte[] data) throws InvalidProtocolBufferException; 122 123 /** 124 * Parses {@code data} as a message of {@code MessageType}. This is just a small wrapper around 125 * {@link #parseFrom(CodedInputStream, ExtensionRegistryLite)}. 126 */ parseFrom(byte[] data, ExtensionRegistryLite extensionRegistry)127 public MessageType parseFrom(byte[] data, ExtensionRegistryLite extensionRegistry) 128 throws InvalidProtocolBufferException; 129 130 /** 131 * Like {@link #parseFrom(byte[], int, int)}, but does not throw an exception if the message is 132 * missing required fields. Instead, a partial message is returned. 133 */ parsePartialFrom(byte[] data, int off, int len)134 public MessageType parsePartialFrom(byte[] data, int off, int len) 135 throws InvalidProtocolBufferException; 136 137 /** 138 * Like {@link #parseFrom(ByteString, ExtensionRegistryLite)}, but does not throw an exception if 139 * the message is missing required fields. Instead, a partial message is returned. 140 */ parsePartialFrom( byte[] data, int off, int len, ExtensionRegistryLite extensionRegistry)141 public MessageType parsePartialFrom( 142 byte[] data, int off, int len, ExtensionRegistryLite extensionRegistry) 143 throws InvalidProtocolBufferException; 144 145 /** 146 * Like {@link #parseFrom(byte[])}, but does not throw an exception if the message is missing 147 * required fields. Instead, a partial message is returned. 148 */ parsePartialFrom(byte[] data)149 public MessageType parsePartialFrom(byte[] data) throws InvalidProtocolBufferException; 150 151 /** 152 * Like {@link #parseFrom(byte[], ExtensionRegistryLite)}, but does not throw an exception if the 153 * message is missing required fields. Instead, a partial message is returned. 154 */ parsePartialFrom(byte[] data, ExtensionRegistryLite extensionRegistry)155 public MessageType parsePartialFrom(byte[] data, ExtensionRegistryLite extensionRegistry) 156 throws InvalidProtocolBufferException; 157 158 /** 159 * Parse a message of {@code MessageType} from {@code input}. This is just a small wrapper around 160 * {@link #parseFrom(CodedInputStream)}. Note that this method always reads the <i>entire</i> 161 * input (unless it throws an exception). If you want it to stop earlier, you will need to wrap 162 * your input in some wrapper stream that limits reading. Or, use {@link 163 * MessageLite#writeDelimitedTo(java.io.OutputStream)} to write your message and {@link 164 * #parseDelimitedFrom(InputStream)} to read it. 165 * 166 * <p>Despite usually reading the entire input, this does not close the stream. 167 */ parseFrom(InputStream input)168 public MessageType parseFrom(InputStream input) throws InvalidProtocolBufferException; 169 170 /** 171 * Parses a message of {@code MessageType} from {@code input}. This is just a small wrapper around 172 * {@link #parseFrom(CodedInputStream, ExtensionRegistryLite)}. 173 */ parseFrom(InputStream input, ExtensionRegistryLite extensionRegistry)174 public MessageType parseFrom(InputStream input, ExtensionRegistryLite extensionRegistry) 175 throws InvalidProtocolBufferException; 176 177 /** 178 * Like {@link #parseFrom(InputStream)}, but does not throw an exception if the message is missing 179 * required fields. Instead, a partial message is returned. 180 */ parsePartialFrom(InputStream input)181 public MessageType parsePartialFrom(InputStream input) throws InvalidProtocolBufferException; 182 183 /** 184 * Like {@link #parseFrom(InputStream, ExtensionRegistryLite)}, but does not throw an exception if 185 * the message is missing required fields. Instead, a partial message is returned. 186 */ parsePartialFrom(InputStream input, ExtensionRegistryLite extensionRegistry)187 public MessageType parsePartialFrom(InputStream input, ExtensionRegistryLite extensionRegistry) 188 throws InvalidProtocolBufferException; 189 190 /** 191 * Like {@link #parseFrom(InputStream)}, but does not read until EOF. Instead, the size of message 192 * (encoded as a varint) is read first, then the message data. Use {@link 193 * MessageLite#writeDelimitedTo(java.io.OutputStream)} to write messages in this format. 194 * 195 * @return Parsed message if successful, or null if the stream is at EOF when the method starts. 196 * Any other error (including reaching EOF during parsing) will cause an exception to be 197 * thrown. 198 */ parseDelimitedFrom(InputStream input)199 public MessageType parseDelimitedFrom(InputStream input) throws InvalidProtocolBufferException; 200 201 /** Like {@link #parseDelimitedFrom(InputStream)} but supporting extensions. */ parseDelimitedFrom(InputStream input, ExtensionRegistryLite extensionRegistry)202 public MessageType parseDelimitedFrom(InputStream input, ExtensionRegistryLite extensionRegistry) 203 throws InvalidProtocolBufferException; 204 205 /** 206 * Like {@link #parseDelimitedFrom(InputStream)}, but does not throw an exception if the message 207 * is missing required fields. Instead, a partial message is returned. 208 */ parsePartialDelimitedFrom(InputStream input)209 public MessageType parsePartialDelimitedFrom(InputStream input) 210 throws InvalidProtocolBufferException; 211 212 /** 213 * Like {@link #parseDelimitedFrom(InputStream, ExtensionRegistryLite)}, but does not throw an 214 * exception if the message is missing required fields. Instead, a partial message is returned. 215 */ parsePartialDelimitedFrom( InputStream input, ExtensionRegistryLite extensionRegistry)216 public MessageType parsePartialDelimitedFrom( 217 InputStream input, ExtensionRegistryLite extensionRegistry) 218 throws InvalidProtocolBufferException; 219 } 220