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