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